僅需一個依賴給Swagger換上新面板，既簡單又炫酷！

語言: CN / TW / HK
時間 2022-08-04 19:15:03

Swagger作為一款非常流行的API文件生成工具，相信很多小夥伴都在用。Swagger最為方便的地方在於，你的專案只要集成了它，一啟動就能生成最新版文件，而且可以線上除錯。不過Swagger的介面除錯功能確實有很多缺點，比如對JSON支援不太友好。今天我們使用Knife4j來增強下它，使用的是SpringDoc提供的Swagger實現庫，希望對大家有所幫助！

SpringBoot實戰電商專案mall（50k+star）地址：http://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相關依賴；

```xml

com.github.xiaoymin knife4j-springdoc-ui 3.0.3 ```

  • 然後將專案啟動起來，訪問下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包。

專案地址

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

總結

像Knife4j這種，不改變Swagger原來的使用，能對Swagger進行功能增強的庫確實很不錯。要是能多幾種這種換面板的實現庫的話，Swagger的使用體驗應該會更好！

專案原始碼地址

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

「其他文章」
「」
「」