当前位置：网站首页>Just one dependency to give swagger a new skin, which is simple and cool

Just one dependency to give swagger a new skin, which is simple and cool

2022-07-22 05:46:00 【InfoQ】

Swagger As a very popular API Document generation tool , I believe many friends are using .Swagger The most convenient place is , 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 The interface debugging function of does have many disadvantages , For example, yes. JSON The support is not very friendly . Today we use Knife4j To enhance it , It uses SpringDoc Provided Swagger Implementation library , I hope that's helpful ！

Chat Swagger Of Java library

First, let's talk about Java The two more popular Swagger Implementation library , Compare which is better .

SpringFox

SpringFox It's old school Swagger Implementation library ,Github Superscript star 5.6K+, I believe that this library is integrated in many small partner projects . However, the implementation library was released two years ago 3.0.0 No version has been released since version . And if you're SpringBoot 2.6.x Version above , You will find many problems that need to be solved by yourself , For details, refer to upgrading SpringBoot 2.6.x After version ,Swagger It's useless ！ .

SpringDoc

SpringDoc It has only recently become popular Swagger Implementation library ,Github Superscript star 2K+, The version update is still very fast , Maintenance and update are guaranteed . I wrote one before SpringDoc Use the tutorial You can refer to it .

SpringDoc The function of is still very powerful , Not only support Spring WebMvc project , It can also support Spring WebFlux project .

Which one to choose

If your project has integrated SpringFox And a lot of , Still use SpringFox Well , After all, migration also requires cost . If your project is a new project and is currently in the stage of technology selection, you can consider using SpringDoc, After all, update and maintenance are more guaranteed .

SpringDoc combination Knife4j Use

Knife4j Is a Swagger UI Enhanced library , I always thought it only supported SpringFox, Recently found that it also supports SpringDoc.Knife4j It can be supported seamlessly SpringDoc, Just add a dependency , There is no need to modify any usage , Very convenient ！

We're still going to use it here SpringDoc Use the tutorial Medium mall-tiny-springdocDemo, First, in the pom.xml Add Knife4j Related dependencies ;

<!--Knife4j Of Swagger Skin dependence -->
<dependency>
 <groupId>com.github.xiaoymin</groupId>
 <artifactId>knife4j-springdoc-ui</artifactId>
 <version>3.0.3</version>
</dependency>

Then start the project , Access to the Knife4j Default interface document address ：http://localhost:8088/doc.html

We are looking for one that needs to be submitted JSON Interface debugging of format request parameters , Find out about JSON Format parameters ,Knife4j Provides format verification function ;

Find another interface with long return data to debug ,Knife4j Provides data folding function , These two functions are really what we need .

Knife4j Microservice solution update

There was a set of micro service aggregation before Swagger Of API Document solutions , Also used. Knife4j, It has recently been updated to support the latest version Spring Cloud, Here we talk about this solution .

Realization principle

Our ideal solution should be like this , Gateway as API Unified access to documents , The gateway aggregates the documents of all microservices , By switching at the gateway to achieve other services API Access to documents .

Related service division ：

micro-knife4j-gateway： Gateway service , As a micro service API Access to documents , Aggregate all API file , Need to introduce the document front end UI package ;

micro-knife4j-user： Customer service , Ordinary API service , There is no need to introduce a document front end UI package ;

micro-knife4j-order： Order service , Ordinary API service , There is no need to introduce a document front end UI package .

Project address

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

summary

image Knife4j such , Don't change Swagger The original use , Be able to Swagger The library with enhanced functions is really good . If there are more implementation libraries of this skin changing ,Swagger The user experience should be better ！