今天這篇文章介紹一下微服務如何聚合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關鍵程式碼就介紹完了,詳細配置見原始碼。
案例原始碼已上傳GitHub,關注VX:碼猿技術專欄,回覆關鍵:9529 獲取!
2、微服務引用swagger-starter
單個微服務引用就很簡單了,只需要新增如下依賴:
<dependency>
<groupId>cn.myjszl</groupId>
<artifactId>swagger-starter</artifactId>
</dependency>
接下來只需要在配置檔案配置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方法,程式碼如下:
案例原始碼已上傳GitHub,關注VX:碼猿技術專欄,回覆關鍵:9529 獲取!
好了,閘道器的配置這裡就完成了。
此時啟動閘道器、訂單、庫存服務,直接訪問閘道器的文件:http://localhost:3001/doc.html,結果如下圖:
API文件好用的功能介紹
不得不說這款Swagger UI 介面還是比較簡單易用的,個人用起來還不錯。
1、搜尋功能
在右上角的搜尋功能可以根據介面描述搜尋相關的介面資訊,如下圖:
2、離線文件
可以直接拷貝文件的MarkDown形式轉換成Html或者PDF生成離線文件,如下圖:
3、令牌配置
在訪問需要認證的介面時,可以通過配置令牌,這樣令牌將會全域性生效,不必每個請求都要配置一遍,如下:
4、配置快取
該文件的所有配置,包括請求引數、授權令牌等資訊都是快取的,也就是說配置一次,下次再開啟的時候也是預設存在的。
5、全域性引數配置
對於一些全域性的引數,比如請求頭中需要攜帶請求客戶端、版本號等資訊,可以在全域性引數中配置,如下:
總結
本篇文章介紹了微服務整合閘道器聚合Swagger文件,開發中非常實用。