Spring Boot | Using SWAGGER at maximum

Let’s learn about Swagger 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)

Stefan Paladuta — History of the Swagger

• 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.

The point illustrated in a picture | by Stefan Paladuta

• Springfox is a framework that acts as the “glue” between Swagger and Spring. It generates the specification (contract) based on your code and also deploys the Swagger UI client with your application, allowing you to immediately test your REST API
• Swagger is a RESTful API specification, meaning that it can be used to document APIs that follow the REST architectural style. NOTE: This doesn’t mean it works just with JSON. Even if just a few people that are confusing REST architectural with mandatory format JSON , please don’t. As REST arch. doesn’t impose the use of JSON and actually XML can also be used in swagger-ui.
• Swagger is not a replacement for documentation, meaning that it should be used in addition to other forms of documentation such as user manuals and tutorials
• The springdoc-openapi Java library helps automating the generation of API documentation using Spring Boot projects.

I divide this article in the following part(s):

• Chapter 1 Doing the first steps to implement swagger in my project (using springfox implementation)
• Chapter 2 Doing the first steps to implement swagger in my project (using springdoc implementation)
• Chapter 3 Going deeper to see what tricks and tip’s we can extract
• Chapter 4 Swagger version 2 vs Swagger version 3
• Chapter 5 Kudos to the creator of swager-springmvc
• Chapter 6 My final thoughts

Chapter 1 Doing the first steps to implement swagger in my project (using springfox implementation)

As I hope it’s clear from the title I will be using spring boot in this article so starting with the simple article: https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api as any programmer I start doing the steps:

Step 1 Introduce the dependencies (if you are using version 3)

<dependency> 
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

using the command: mvn dependecy:tree on the root of the project where the pom.xml is we can see, that it brings:

• io.springfox:springfox-oas.jar (v: 3.0.0)
• io.springfox:springfox-data-rest.jar (v: 3.0.0)
• io.springfox:springfox-bean-validators.jar (v: 3.0.0)
• io.springfox:springfox-swagger2.jar (v: 3.0.0)
• io.springfox:springfox-swagger-ui (v: 3.0.0)
• […]and other small things we don’t need to concern now[…]

so it brings quite a lot of stuff. Actually just for fun I can tell you the dimensione of the .jar(s) just for fun ofcourse:

io.springfox:springfox-oas.jar (v: 3.0.0) 77.6KB
io.springfox:springfox-data-rest.jar (v: 3.0.0) 69.6KB
io.springfox:springfox-bean-validators.jar (v: 3.0.0) 37.7KB
io.springfox:springfox-swagger2.jar (v: 3.0.0)107KB
io.springfox:springfox-swagger-ui (v: 3.0.0) 2.60MB

Step 2 Creation of the Docket Bean

Now I will create the Docket bean.

package ro.stefan.demo.swaggeradvanced.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class SpringFoxConfig {
  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build();
  }
}

Step 3 Start the project

Starting the project … but suprise, suprise[…] If you have years in software engineering you know until this moment that tutorials don’t reflect 100% reality, and thus my article following the manual of how to mount Swagger system in my microservice fails, because of the error:

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
    at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:176) ~[spring-context-4.3.3.RELEASE.jar!/:4.3.3.RELEASE]
    at org.springframework.context.support.DefaultLifecycleProcessor.access$200(DefaultLifecycleProcessor.java:51) ~[spring-context-4.3.3.RELEASE.jar!/:4.3.3.RELEASE]

this error is solved easy by doing this steps (+why this error exist it explains in the same post) https://stackoverflow.com/questions/40241843/failed-to-start-bean-documentationpluginsbootstrapper-in-spring-data-rest but this does bring up a point: Is better to switch to oficialy Spring Boot docs ? maybe but I’m here to show first what’s with Swagger.

After you start the project you must go to: localhost:<yourPort>/swagger-ui/index.html and we can see:

let’s analyse the elements:

Element: Select a definition

Explanation in this small guideline made by me: https://medium.com/@stefan.paladuta17/spring-boot-using-swagger-at-maximum-grouping-definition-tag-2b25eb39a0cb

Element: basic-error-controller

Explanation: we didn’t say to docker what packages to scan and what packages to not scan.

Element: OAS3

Explanation: Marks that the UI was constructed around Specification v3

Element: Schemas

Explanation: https://medium.com/@stefan.paladuta17/spring-boot-using-swagger-at-maximum-grouping-definition-tag-2b25eb39a0cb

or we can use the old version 2 (I prefer to show to my audience all the ways so that no confusion will appear when consulting multiple sources of inspiration)

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.3.1</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.3.1</version>
</dependency>

• Springfox has evolved from a project originally created by Marty Pitt and was named swagger-springmvc. Much kudos goes to Marty.
• springfox-swagger is an implementation of this specification based on the Spring ecosystem.
• springfox-swagger-ui encapsulates swagger-ui, making it possible to use Spring services.

Chapter 2 Doing the first steps to implement swagger in my project (using springdoc implementation)

Even if sprinfox implementation was dear to my heart because of multiple reasons that I wrote in one article (https://medium.com/@stefan.paladuta17/swagger-spring-boot-bye-bye-swagger-specifications-and-welcome-openapi-specifications-7eab7e68d6d7) I must go to a more stable product.

To see the steps necessary to implement spring-doc in your project I created the following article: <inConstruction> please take a look as I’m sure it’s going to bring you a lot of value.

Chapter 3 Going deeper to see what tricks and tip’s we can extract

Swagger can do very interesting things if you go deeper in it (reading the freaking manual 😊 )

Please read my sub-article (the current one represents the main that binds all together): https://medium.com/@stefan.paladuta17/spring-boot-using-swagger-at-maximum-docket-advanced-details-6b72b334be21

• Concept of global response
• Concept of global request parameters
• Adding extra models to the current generate openAPI json.
• What we are producing and consuming as software.

Also the following: https://medium.com/@stefan.paladuta17/spring-boot-using-swagger-at-maximum-apiinfo-ef2ba65ebb86 touches the concept of general information regarding Who, When, What

Chapter 4 Swagger version 2 vs Swagger version 3

OAS 3.0 was the first major release since the specification was donated to the OpenAPI Initiative, and renamed from the Swagger Specification to OpenAPI Specification in 2015. — https://swagger.io/blog/news/whats-new-in-openapi-3-0/

Point 1: OAS 3.0 introduces a new, more simplified structure

This refers to the fact that the json you got when you accessed http://localhost:<port>/v3/api-docs (for v3) and http://localhost:<port>/v2/api-docs (for v2) has the following structure changed:

the diagram displays some changed that happen at json level in a component matter, from a json point of view we will see simply (left v2, right v3):

Simple example of diff. between v2 spec and v3 spec

Point 2: Updated Parameter Types

As previously mentioned, OAS 3.0 removed two parameter types: body and formdata. OAS 3.0 also introduced a new parameter type, cookie, which was a requested update for documenting APIs that currently use cookies.

That’s great news because now our API’s that are accepting cookies can have a proper documentation.

Example of SWAGGER-UI with an endpoint that accepts cookie

Point 3: Added support for multiple root URLs.

Now we can finally have in our Swagger-UI the possibility of testing our API from multiple hosts.

EXTRA: [Java] [SpringBoot] Bye Bye swagger specifications and welcome OpenAPI specifications

To go deeper with the same quality of materials I love to create please refer to this sub-tutorial I created: https://medium.com/@stefan.paladuta17/swagger-spring-boot-bye-bye-swagger-specifications-and-welcome-openapi-specifications-7eab7e68d6d7

NOTE: OAS 3.0 moves from GitHub Flavored Markdown (GFM) to CommonMark support.

Chapter 5 Kudos to the creator of swager-springmvc

Springfox has evolved from a project originally created by Marty Pitt and was named swagger-springmvc. Much kudos goes to Marty. — https://springfox.github.io/springfox/docs/snapshot/

Marty Pitt

If you want to see what Marty is doing this days here you can follow him:

1. GitHub: https://github.com/martypitt
2. Twitter: https://twitter.com/marty_pitt
3. Linkedin: https://www.linkedin.com/in/martypitt/recent-activity/
4. Medium: https://medium.com/@martypitt
5. Blog: https://blog.vyne.co/author/marty/
6. Podcast about his new projects: https://bootifulpodcast.podbean.com/e/springfox-creator-marty-pitt-on-swagger-vyne-and-taxi-lang-and-much-more/

Chapter 6 My final thoughts

Firstly I’m not a grammar nazi and will never be as I struggle with my dyslexia daily and it’s really a limitation on what careers I can touch in my life, but programming was always my to go place as it’s much easier for me to understand. One of the things that makes my life easy (and I hope to most of you) and represents actually the first point is being able to understand exactly what/where are specific terms used correctly.

When someone talks about swagger, based on the context I usually understand if he means about the specification or the UI, but I prefer to remind everyone that swagger is a term that described not one thing but n things (Swagger docs: “Swagger is a powerful yet easy-to-use suite of API developer tools”)

The point illustrated in a picture | by Stefan Paladuta

Secondly creation of API documentation is a must and even this for me it’s not enough. In my daily work I always have the SWAGGER-UI + documentation (more detailed) written in confluence pages (in my case) + a tone of other details in README.md file of the project that generates the swagger-ui. It may be an overkill but I always considered better to have more documentation rather to work on a project where everyone doesn’t know s^_^t.

Thirdly fun fact if you didn’t read the about section on the official swagger page, they also made SoapUI, and that product was a big success as it was used by almost EVERYBODY (before postman landed for rest API’s 😋).

Fortly the relationship between Springfox and Swagger:

Swagger is a specification. springfox-swagger is an implementation of this specification based on the Spring ecosystem. springfox-swagger-ui is an encapsulation of swagger-ui so that it can use Spring’s services.

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:

OpenAPI Specification - Wikipedia

springdoc-openapi (Spring Boot)

Documenting your REST API with Swagger and Springfox

Setting up Swagger 3 With Spring Boot 2

OpenAPI spec (swagger) v2 vs v3

Advanced Swagger Configuration with Spring Boot

Springfox Reference Documentation

Swagger天天用，但它背后的实现原理很多人都不知道！