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

語言: CN / TW / HK

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

「其他文章」