乐趣区

关于java:仅需一个依赖给Swagger换上新皮肤既简单又炫酷

jiezi

Swagger 作为一款十分风行的 API 文档生成工具，置信很多小伙伴都在用。Swagger 最为不便的中央在于，你的我的项目只有集成了它，一启动就能生成最新版文档，而且能够在线调试。不过 Swagger 的接口调试性能的确有很多毛病，比方对 JSON 反对不太敌对。明天咱们应用 Knife4j 来加强下它，应用的是 SpringDoc 提供的 Swagger 实现库，心愿对大家有所帮忙！

SpringBoot 实战电商我的项目 mall（50k+star）地址：https://github.com/macrozheng/mall

聊聊 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…

总结

像 Knife4j 这种，不扭转 Swagger 原来的应用，能对 Swagger 进行性能加强的库的确很不错。要是能多几种这种换皮肤的实现库的话，Swagger 的应用体验应该会更好！

我的项目源码地址

https://github.com/macrozheng…

退出移动版