Swagger作为一款非常流行的API文档生成工具，相信很多小伙伴都在用。Swagger最为方便的地方在于，你的项目只要集成了它，一启动就能生成最新版文档，而且可以在线调试。不过Swagger的接口调试功能确实有很多缺点，比如对JSON支持不太友好。今天我们使用Knife4j来增强下它，使用的是SpringDoc提供的Swagger实现库，希望对大家有所帮助！
聊聊Swagger的Java库
首先我们来聊聊Java中两种比较流行的两种Swagger实现库，对比下哪个更好用。
SpringFox
SpringFox是老牌的Swagger实现库，Github上标星5.6K+，相信很多小伙伴项目中都集成的是这个库。不过该实现库在两年前发了3.0.0版本后就再也没发版本了。而且如果你在SpringBoot 2.6.x版本以上使用的话，会发现许多问题需要自行解决，具体可以参考升级 SpringBoot 2.6.x 版本后，Swagger 没法用了！ 。
0a40cb95afc12aef5812dc0f6169c960_76e45fe52da24f3aa7215a4ad4bd0e72_from=pc.png
SpringDoc
SpringDoc是最近才流行起来的Swagger实现库，Github上标星2K+，版本更新还是很快的，维护更新有保障。之前写过一篇SpringDoc使用教程 大家可以参考下。
SpringDoc的功能还是挺强大的，不仅支持Spring WebMvc项目，还可以支持Spring WebFlux项目。
9c949e6dc7aa9e71366b941bbd687d96_31c8edd7b009415082b7fc94209e6528_from=pc.png
该选哪个
如果你的项目中已经集成了SpringFox并大量使用了，还是依然使用SpringFox吧，毕竟迁移也是需要成本的。如果你的项目是新项目目前正在技术选型阶段可以考虑使用SpringDoc，毕竟更新维护更有保障。
SpringDoc结合Knife4j使用
Knife4j是一款Swagger UI增强库，之前一直以为它只支持SpringFox，最近发现它也支持了SpringDoc。Knife4j可以无缝支持SpringDoc，仅需添加一个依赖即可，无需修改任何用法，非常方便！
- 这里我们还是使用SpringDoc使用教程 中的mall-tiny-springdocDemo，首先在pom.xml中添加Knife4j相关依赖；
<!--Knife4j的Swagger皮肤依赖-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-springdoc-ui</artifactId>
<version>3.0.3</version>
</dependency>
- 然后将项目启动起来，访问下Knife4j的默认接口文档地址：http://localhost:8088/doc.html
aa8a403eb85eac2be25e0b8596995c8d_855265eb463c4afbb448051800935e6c_from=pc.png
- 我们找一个需要提交JSON格式请求参数的接口调试下，发现对于JSON格式参数，Knife4j提供了格式校验功能；
9293fc87e5343992d9775cc0501a0d39_ce9dab7a95a748b299a7b2a355cb210d_from=pc.png
- 再找个返回数据比较长的接口调试下，Knife4j提供了数据折叠功能，这两个功能确实是我们比较需要的。
019001401589531a72951cf10e6c1fa2_3782ec991dbb458d8adb3a7826022e1a_from=pc.png
Knife4j微服务解决方案更新
之前出了套微服务聚合Swagger的API文档解决方案 ，也使用了Knife4j，最近把它更新支持了最新版Spring Cloud，这里我们再来聊聊这个解决方案。
实现原理
我们理想的解决方案应该是这样的，网关作为API文档的统一入口，网关聚合所有微服务的文档，通过在网关进行切换来实现对其他服务API文档的访问。
相关服务划分：
- micro-knife4j-gateway：网关服务，作为微服务API文档的访问入口，聚合所有API文档，需要引入文档前端UI包；
- micro-knife4j-user：用户服务，普通API服务，不需要引入文档前端UI包；
- micro-knife4j-order：订单服务，普通API服务，不需要引入文档前端UI包。
项目地址
https://github.com/macrozheng/springcloud-learning/tree/master/micro-knife4j
总结
像Knife4j这种，不改变Swagger原来的使用，能对Swagger进行功能增强的库确实很不错。要是能多几种这种换皮肤的实现库的话，Swagger的使用体验应该会更好！
项目源码地址
https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-springdoc
网友评论