The main article that bundles all together and redirects to different features that you can implement in swagger UI is present here: https://medium.com/@stefan.paladuta17/spring-boot-using-swagger-at-maximum-9828ae9fb9d0
In this article I am going to present what the implementation of springfox v3 (that is complain with OpenAPI specifications) brings to the table.
The article will be divided in the following chapters:
- Chapter 1 Introduce the feature in your project.
- Chapter 2 Is there a need for annotation to enable OAS 3.0 ?
- Chapter 3 Disable for production environment swagger.
- Chapter 4 Problems with the 3rd version
Before starting here are some link(s) that you may be interested in:
- Repository of springfox: https://github.com/springfox/springfox
- Release notes for the version3: https://newreleases.io/project/github/springfox/springfox/release/3.0.0
Chapter 1 Introduce the feature in your project
Step 1 Introduce the dependency in your spring boot project (in pom.xml):
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
Step 2 Creating a Controller , a Dto and a config class to store the Docket Bean
the controller:
import java.util.ArrayList;
import java.util.List;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.annotations.Api;
import ro.stefan.dto.Book;
@RestController
@Api(tags = "Book Controller")
public class BookController {
@GetMapping("/books")
public List<Book> getBooks(){
return new ArrayList<Book>();
}
@GetMapping("/ping")
public String ping() {
return "pong";
}
}
the dto:
public class Book {
private String title;
private String author;
public String getTitle() {
return title;
}
public void setTitle(String title) {
this.title = title;
}
public String getAuthor() {
return author;
}
public void setAuthor(String author) {
this.author = author;
}
}
the configuration docket:
import java.util.HashSet;
import java.util.Set;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class SpringFoxConfig {
@Bean
public Docket getDocketInstanceEx1() {
final Set<String> produces = new HashSet<String>();
produces.add(MediaType.APPLICATION_JSON_VALUE);
produces.add(MediaType.APPLICATION_XML_VALUE);
return new Docket(DocumentationType.OAS_30)
.apiInfo(new ApiInfoBuilder()
.title("Note API")
.description("A CRUD API to demonstrate Springfox 3 integration")
.version("0.0.1")
.license("MIT")
.licenseUrl("https://opensource.org/licenses/MIT")
.build())
.produces(produces).consumes(produces)
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
.build();
}
}
Step 3 Access to the generated OpenAPI
Location: http://localhost:/v3/api-docs and the result is:
This version of springfox implementation fills a lot of gaps that another project called springdoc-openapi had addressed for a long time.
Before going further I will remind everybody that:
- OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API.
- Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs.
Chapter 2 Is there a need for annotation to enable OAS 3.0 ?
This question is actually thanks to https://www.springcloud.io/post/2022-02/springboot-swagger3/#gsc.tab=0 that explains the fact why some tutorials guide you to add the annotation @EnableOpenApi to enable OpenAPI. Actually is wrong (or useless) and actually if you already have a workable project with this annotation, just remove it and tell me the contrary. But why ? because if you go into the jar springfox-boot-starter-3.0.0.jar you can find a spring.factories. Opening the file (.jar):
the following content is presented:
# Auto Configure
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
springfox.boot.starter.autoconfigure.OpenApiAutoConfiguration
NOTE: For people not familiar with Spring Boot this is a Spring Boot-specific SPI file that automatically discovers and registers the configuration of the Starter component.
And if you use your eclipse (with JadClipse — decompiler) to look inside the jar:
we can find in the class: OpenApiAutoConfiguration with the piece of code:
@ConditionalOnProperty(value = “springfox.documentation.enabled”, havingValue = “true”, matchIfMissing = true)
that makes the annotation @EnableOpenApi uselless, because the interface that represents the annotation is importing this class OpenApiDocumentationConfiguration.class
@Import(OpenApiDocumentationConfiguration.class)
public @interface EnableOpenApi {
}
that already activates swagger by default.
Chapter 3 Disable for production environment swagger
NOTE: This is not a feature really of v3, but actually a trick using the previous chapter.
Imagine that if you are like me a developer working in a company your software will go through multiple environments: DEVELOPING, TESTING, UAT (User Acceptance Tests), PRODUCTION (just as example) and we for sure don’t want in PRODUCTION to permit the Spring Boot project to generate a Swagger-UI (not always but in my case yes).
For sure this is possible and quite simple if you read my previous Chapter 2 you have seen that we found a class called: OpenApiDocumentationConfiguration.class that we know is responsible to enable or disabled swagger-ui (by default it’s ON), to turn it OFF we simply must go to our application properties or yaml (depends what we choose to have in our spring boot app) and write the following config if you are using .yaml format:
springfox:
documentation:
enabled: false
or this format if you are using .properties format
springfox.documentation.enabled=false
and that’s all, now the url to swagger-ui will not work anymore.
Chapter 4 Problems with the 3rd version
Even if I’m very dear to swagger I think it was some very big problems regarding code pollution that I hope I have time to write an article about. I wanted to show you guys a lot of new feature that SpringFox implementation brings with the OpenAPI specifications but sadly most of them are buggy or are done wrong, an example is the concept of multiple servers:
As many things this feature is buggy and not working properly: https://github.com/springfox/springfox/issues/3483 and we waited for too long for such a simple feature to be working again. With other words in the next weeks I will be more focus on displaying some alternatives to SpringFox. If I will discover new stuff I will keep this page updated.
Second problem is the lack of transparency. A lot of milestone was set on this project but none of them presented for you as consumer a release date thus making you feel unsecure regarding what to do, to wait or not ? Sadly it’s clear that we as developers can’t wait and we must go forward with projects that are more active like spring-doc (that I will cover in future articles).
Third problem that scared me is the number of things I did on old microservices projects (SpringBoot 2.6.0) because OAS 3.0 from springfox didn’t work, more details can be found here: https://stackoverflow.com/questions/70178343/springfox-3-0-0-is-not-working-with-spring-boot-2-6-0
NOTE: This is my personal opinion and should be taken as being just a view on the project springfox. Again this project is dear to me and I really wanted to talk about it a lot but I want to deliver more value, not to wait for miracles.
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 (;
Top comments (0)