Spring Boot | Using SpringDoc at maximum

Let’s learn about Swagger with SpringDoc implementation in a more deeper article.

So let’s start with the famous question Swagger vs OpenAPI:

Although the terms once referred to the same thing, they can no longer be used interchangeably…even though some people still do, in 2021 OpenAPI refers to the industry-standard specification for RESTful API design. Swagger refers to a set of SmartBear tools. — https://nordicapis.com/

To better understand this kind of political things I like to create timelines, so I created a timeline based on my weeks of research (if something is wrong please feel free to comment bellow as it helps us all to publish articles/tutorial/etc. that are more useful and true to the meaning)

FACTS:

• Swagger is a language-agnostic specification, meaning that it can be used with any programming language. NOTE: Here we can consider this point like the relation between JPA and HIBERNATE. JPA is a specification that HIBERNATE (the library) used as “RULES” in defining a workable code that every developer can use.
• Spring-Doc is a java library
• Spring-Doc automatically generates documentation in JSON/YAML and HTML format APIs. This documentation can be completed by comments using swagger-api annotations.
• The first commit done on this project was on July 21, 2019 v0.0.14

This article is divided into the following sections:

• Section 1 History
• Section 2 Why is it good ?
• Section 3 What I need to learn ?

Section 1 History

Photo by Tanner Mardis on Unsplash

Spring-doc library was created by Badr Nasslahsen (great video presented by him here: https://www.youtube.com/watch?v=utRxyPfFlDw&ab_channel=SpringI%2FO) and you can also follow him on linkedin for some great materials: https://www.linkedin.com/in/nasslahsen/

So based on the previous facts (introduction section) it’s clear that SpringDoc is an implementation of a set of specifications and this set of specification is called OpenAPI more specific version nr. 3. Spring-Doc is the response to the following 2 problems

1. In Java we needed ASAP a tool to generate the OpenAPI v3 specs like we had on version 2 with spring-fox.
2. A better and more transparent release plan of this implementation and stable work, a thing that spring-fox didn’t have the power to offer in the last period.

Section 2 Why is it good ?

Photo by Diana Polekhina on Unsplash

When following a “code first” approach in API development, we first start with writing code, and then we generate the API specification from the code, which then becomes the documentation.

“Code first” is not the only way to develop an API. “API first” is another option where we do exactly the opposite. First, we write the specification, and then we generate code from that specification and implement against it.

So having this library to execute the strategy “API first” is important when you work in a high level environments where your applications communicates with a tone of other sub-systems and you manage multiple projects. In this kind of scenario most of the times you will have analysts that should understand each project and have a view. This view can be touched better and understood from the first steps if something is wrong or not if we do API first approach. We can start by creating first some dummy API’s signatures so that the analyst can have a better imagine of what will happen and actually do simulations.

Pair this with Agile approach and good analysts and you may have the formula for a nice life at work.

Section 3 What I need to learn ?

Learn how to migrate from the current spring-fox implementation to spring-doc implementation: https://medium.com/@stefan.paladuta17/openapi-creating-an-api-description-of-your-project-using-springdoc-implementation-f101019b7f8b

If you aren’t in this situation then in that case I encourage you to still read the post I wrote upper as it will introduce you into the syntax and annotations used with Spring-Doc.

A very important point also is the security schemes can be very powerful and I present them here: <WORK IN PROGRESS>

NOTE: version 2 and version 3 are very different if you want to know why just read my article that talks a lot about the version 2 with the spring-fox implementation: https://medium.com/@stefan.paladuta17/spring-boot-using-swagger-at-maximum-9828ae9fb9d0

If you liked the article please take a minute to offer me a clap 👏 or even buy me a coffee https://www.buymeacoffee.com/stefansplace (;

References:

Microservices API Documentation with Springdoc OpenAPI

OpenAPI vs Swagger: ❗️ An In-Depth Clarification

'Code First' API Documentation with Springdoc and Spring Boot