微服務如何聚合 API 文檔？這波秀~
今天這篇文章介紹一下微服務如何聚合Swagger實現接口文檔管理。
文章目錄如下：
為什么需要聚合?
微服務模塊眾多，如果不聚合文檔，則訪問每個服務的API文檔都需要單獨訪問一個Swagger UI界面，這么做客戶端能否接受?
反正作為強迫癥的我是接受不了.......
既然使用了微服務，就應該有統一的API文檔入口。
如何聚合?
統一的文檔入口顯然應該聚合到網關中，通過網關的入口統一映射到各個模塊。
演示
本文采用Spring Cloud Gateway 聚合 Swagger的 方式 生成API文檔。
案例源碼結構如下：
本文只介紹如何聚合Swagger，關于網關、注冊中心等內容不再介紹，有不了解的看陳某前面文章。
單個服務如何聚合Swagger?
這里的單個服務不包括網關，網關需要單獨配置。
單個服務聚合其實很簡單，就是普通的Spring Boot 整合 Swagger，但是微服務模塊眾多，不能每個微服都整合一番，因此可以自定義一個swagger-starter，之后每個微服務都依賴這個starter即可。
詳細的步驟如下：
1、創建swagger-starter
自定義starter這里就不再介紹了，都是基礎的知識;
目錄結構如下：
1）添加依賴
對于Swagger原生的UI界面陳某不太喜歡，因此使用了一款看起來還不錯的UI界面，依賴如下：
<!--swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
</dependency>
<!--swagger-ui 這里是用了一個好看一點ui界面-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
</dependency>
對于UI界面，每個人審美不同，選擇自己喜歡的就好。
2）自動配置類配置Swagger
陳某是將每個服務的API信息抽離出一個屬性類SwaggerProperties，后續只需要在每個服務的配置文件中指定即可。
@Data
@ConfigurationProperties(prefix = SwaggerProperties.PREFIX)
@Component
@EnableConfigurationProperties
public class SwaggerProperties {
public static final String PREFIX="spring.swagger";
//包
private String basePackage;
//作者相關信息
private Author author;
//API的相關信息
private ApiInfo apiInfo;
@Data
public static class ApiInfo{
String title;
String description;
String version;
String termsOfServiceUrl;
String license;
String licenseUrl;
}
@Data
public static class Author{
private String name;
private String email;
private String url;
}
}
對于Swagger的配置其實很簡單，分為如下部分：
- API文檔基本信息配置
- 授權信息配置(基于OAuth2的認證配置)
API文檔配置無非就是配置文檔的基本信息，比如文檔標題、作者、聯系方式.....
代碼如下：
授權信息配置也很簡單，就是在全局信息的請求頭中配置一個能夠放置令牌的地方，代碼如下：
此處對應UI界面的地方如下圖：
只需要將獲取token令牌設置到這里即可。
好了，swagger-starter關鍵代碼就介紹完了，詳細配置見源碼。
2、微服務引用swagger-starter
單個微服務引用就很簡單了，只需要添加如下依賴：
@Data
@ConfigurationProperties(prefix = SwaggerProperties.PREFIX)
@Component
@EnableConfigurationProperties
public class SwaggerProperties {
public static final String PREFIX="spring.swagger";
//包
private String basePackage;
//作者相關信息
private Author author;
//API的相關信息
private ApiInfo apiInfo;
@Data
public static class ApiInfo{
String title;
String description;
String version;
String termsOfServiceUrl;
String license;
String licenseUrl;
}
@Data
public static class Author{
private String name;
private String email;
private String url;
}
}
接下來只需要在配置文件配置API相關的信息即可，比如訂單服務的配置如下：
好了，至此單個服務的配置完成了。
此時我們可以驗證一下，直接訪問：http://localhost:3002/swagger-order-boot/v2/api-docs，結果如下圖：
網關如何聚合Swagger?
網關聚合的思想很簡單，就是從路由中獲取微服務的訪問地址，然后拼接上 /v2/api-docs 即可。
同樣的還是要添加Swagger的兩個依賴，如下：
<!--swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
</dependency>
<!--swagger-ui 這里是用了一個好看一點ui界面-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
</dependency>
創建GatewaySwaggerResourcesProvider實現SwaggerResourcesProvider，重寫其中的get方法，代碼如下：
”好了，網關的配置這里就完成了。
此時啟動網關、訂單、庫存服務，直接訪問網關的文檔：http://localhost:3001/doc.html，結果如下圖：
API文檔好用的功能介紹
不得不說這款Swagger UI 界面還是比較簡單易用的，個人用起來還不錯。
1、搜索功能
在右上角的搜索功能可以根據接口描述搜索相關的接口信息，如下圖：
2、離線文檔
可以直接拷貝文檔的MarkDown形式轉換成Html或者PDF生成離線文檔，如下圖：
3、令牌配置
在訪問需要認證的接口時，可以通過配置令牌，這樣令牌將會全局生效，不必每個請求都要配置一遍，如下：
4、配置緩存
該文檔的所有配置，包括請求參數、授權令牌等信息都是緩存的，也就是說配置一次，下次再打開的時候也是默認存在的。
5、全局參數配置
對于一些全局的參數，比如請求頭中需要攜帶請求客戶端、版本號等信息，可以在全局參數中配置，如下：
總結
本篇文章介紹了微服務集成網關聚合Swagger文檔，開發中非常實用。
