## 前言 * Swagger作為接口文檔工具接入springboot工程很方便，只需一個starter，一個configuration就可集成完畢 * 但是對于有較多微服務的系統來說，一個服務一個文檔地址，便會覺得比較麻煩。有沒有什么好的辦法可以都把他們集中起來？ * 這時候聚合文檔的解決方案出現了，將所有的微服務地址以swagger分組的形式展現，切換分組的時候就相當于直接切換了整個微服務。 * BladeX對聚合文檔做了優化，提供了更簡單、配置更方便的解決方案，那么下面我們來看看具體如何操作。 ## 如何配置 * 打開`blade-swagger`工程的配置文件`application.yml` * 配置需要出現在網關的服務地址，以及顯示的服務名，其中`uri`為網關地址，`location`是對應服務名的swagger-api地址  * 對應服務工程引入 blade-core-boot 依賴即可，此依賴會自動加載swagger所需的依賴  ## 文檔地址 1. 我們不妨先打開下聚合文檔的地址，開啟所有增強配置： http://localhost:18000/doc.html **注??：** - **新版本開始把swagger網關單獨抽離到了`blade-swagger`服務，請單獨啟動并訪問** - **雖然swagger服務已經獨立，但仍然需要開啟網關進行服務轉發才可以正常訪問**  2. 點擊左上角的下拉框，我們可以看到已經配置好了3個不同的微服務文檔。  ## API潤色 1. swagger增強插件knife4j有不少好用的功能，我們下面來簡單介紹一下，當然詳細說明請查閱官方文檔：https://doc.xiaominfo.com/docs/features/enhance 2. 首先把個性化配置都打開，**目前knife4j版本刷新后會丟失增強配置，所以需要手動關閉tab，再重新打開文檔頁面才會生效**。  3. 其次加上請求頭的Token值（可以直接從授權模塊獲取），獲取后將Token設置到請求頭中  4. 接著我們在`blade-swagger`的配置文件加上演示模塊并啟動服務    5. 重啟blade-swagger服務后，刷新首頁，就可以在左上角便可以看到對應選項了  6. 若大家想實時修改聚合文檔的信息，可以把`blade-swagger`的聚合文檔配置刪掉，然后到nacos進行新增即可 7. 接著打開演示模塊，以排在第二個的`/blade-demo/getNameByProps`接口為例，我想把他排在第一個，并且以中文形態來描述他的api  8. 找到對應API，加上如下配置，`@ApiOperationSupport`中的`order`就是用來設置排序的，值越小，排序越靠前。  ~~~java @GetMapping("name-by-props") @ApiOperation(value = "查看名稱", notes = "排序測試") @ApiOperationSupport(order = 1) public String getNameByProps() { return properties.getName(); } ~~~ 6. 重啟服務查看聚合文檔，可以看到，排序、中文生效，一個常規的API形態誕生了。  7. 調用下API，返回成功，后續編寫文檔就可以放心的交給對接的團隊啦！  8. 如果有些API我們不想顯示在文檔上，可以使用@ApiIgnore注解，例如我們加在剛剛的方法上 ~~~java @ApiIgnore @GetMapping("name-by-props") @ApiOperation(value = "查看名稱", notes = "排序測試") @ApiOperationSupport(order = 1) public String getNameByProps() { return properties.getName(); } ~~~ 9. 重啟服務，查看文檔界面已經沒有這個API描述了。  ## 注意點 * swagger默認在生產環境`prod`下關閉無法使用，因為在生產環境暴露接口會非常危險 * 若需要開啟，請使用`test`環境啟動測試 ## 結束語 本文講述了聚合文檔的實現以及Swagger接口描述的潤色，想知道更多用法，還需查看官方文檔。 * swagger文檔直達：https://swagger.io/ * swagger-bootstrap-ui文檔直達：https://doc.xiaominfo.com/docs/quick-start