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

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的使用體驗應該會更好！