Only one dependency is needed to give Swagger a new skin, which is simple and cool!

As a very popular API documentation generation tool, Swagger is believed to be used by many small partners. The most convenient part of Swagger is that as long as your project integrates it, the latest version of the document can be generated as soon as it is started, and it can be debugged online. However, Swagger's interface debugging function does have many shortcomings, such as being unfriendly to JSON support. Today we use Knife4j to enhance it, using the Swagger implementation library provided by SpringDoc, I hope it will be helpful to everyone!

SpringBoot actual e-commerce project mall (50k+star) address: https://github.com/macrozheng/mall

Talk about Swagger's Java library

First, let's talk about the two popular Swagger implementation libraries in Java, and compare which one is better.

SpringFox

SpringFox is an old Swagger implementation library. It is marked with a star on Github 5.6K+ . I believe this library is integrated in many small partner projects. However, the implementation library was released two years ago 3.0.0 version and has not been released again.
And if you use SpringBoot version 2.6.x or above, you will find that many problems need to be solved by yourself. For details, please refer to Swagger after upgrading SpringBoot 2.6.x version! .

SpringDoc

SpringDoc is a Swagger implementation library that has only become popular recently. It is marked with a star on Github 2K+ . The version update is still very fast, and the maintenance update is guaranteed. I wrote a SpringDoc tutorial before, you can refer to it.

The functions of SpringDoc are quite powerful, not only supporting Spring WebMvc projects, but also Spring WebFlux projects.

Which to choose

If you have integrated SpringFox in your project and use it a lot, you should still use SpringFox. After all, migration also costs money. If your project is a new project and is currently in the technology selection stage, you can consider using SpringDoc, after all, update and maintenance are more secure.

Using SpringDoc with Knife4j

Knife4j is a Swagger UI enhancement library. I thought it only supported SpringFox before, but recently I found that it also supports SpringDoc. Knife4j can seamlessly support SpringDoc, just add one dependency, no need to modify any usage, very convenient!

• Here we still use the mall-tiny-springdoc Demo in the SpringDoc tutorial , first add Knife4j related dependencies in pom.xml ;

 <!--Knife4j的Swagger皮肤依赖-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-springdoc-ui</artifactId>
    <version>3.0.3</version>
</dependency>

• Then start the project and visit the default interface document address of Knife4j: http://localhost:8088/doc.html

• We found an interface that needs to submit JSON format request parameters and found that for JSON format parameters, Knife4j provides a format verification function;

• Then find an interface with a long return data to debug, Knife4j provides data folding function, these two functions are really needed by us.

Knife4j Microservices Solution Update

A set of API documentation solutions for microservice aggregation Swagger was developed before, and Knife4j was also used. Recently, it has been updated to support the latest version of Spring Cloud. Let's talk about this solution here.

Implementation principle

Our ideal solution should be like this, the gateway acts as a unified entry for API documents, the gateway aggregates the documents of all microservices, and accesses the API documents of other services by switching at the gateway.

Related service division:

• micro-knife4j-gateway: gateway service, as the access entry for microservice API documents, aggregates all API documents, and needs to introduce the document front-end UI package;
• micro-knife4j-user: user service, common API service, no need to introduce document front-end UI package;
• micro-knife4j-order: order service, common API service, no need to introduce document front-end UI package.

project address

https://github.com/macrozheng/springcloud-learning/tree/master/micro-knife4j

Summarize

Libraries like Knife4j that can enhance Swagger without changing the original use of Swagger are really good. If there are more implementation libraries of this kind of skinning, the experience of using Swagger should be better!

Project source code address

https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-springdoc