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 没法用了！ 。

SpringDoc

SpringDoc 是最近才流行起来的 Swagger 实现库，Github 上标星 2K+，版本更新还是很快的，维护更新有保障。之前写过一篇 SpringDoc 使用教程 大家可以参考下。

SpringDoc 的功能还是挺强大的，不仅支持 Spring WebMvc 项目，还可以支持 Spring WebFlux 项目。

该选哪个

如果你的项目中已经集成了 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

• 我们找一个需要提交 JSON 格式请求参数的接口调试下，发现对于 JSON 格式参数，Knife4j 提供了格式校验功能；

• 再找个返回数据比较长的接口调试下，Knife4j 提供了数据折叠功能，这两个功能确实是我们比较需要的。

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

来源：https://mp.weixin.qq.com/s/R-S8nT_apz6CjXN6SqliDQ