微服務如何聚合 API 文檔？這波秀~

2022 年 2 月 14 日
筆記
微服務, Spring Cloud

今天這篇文章介紹一下微服務如何聚合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相關的資訊即可，比如訂單服務的配置如下：

好了，至此單個服務的配置完成了。

此時我們可以驗證一下，直接訪問：//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 獲取！

好了，網關的配置這裡就完成了。

此時啟動網關、訂單、庫存服務，直接訪問網關的文檔：//localhost:3001/doc.html，結果如下圖：

API文檔好用的功能介紹

不得不說這款Swagger UI 介面還是比較簡單易用的，個人用起來還不錯。

1、搜索功能

在右上角的搜索功能可以根據介面描述搜索相關的介面資訊，如下圖：

2、離線文檔

可以直接拷貝文檔的MarkDown形式轉換成Html或者PDF生成離線文檔，如下圖：

3、令牌配置

在訪問需要認證的介面時，可以通過配置令牌，這樣令牌將會全局生效，不必每個請求都要配置一遍，如下：

4、配置快取

該文檔的所有配置，包括請求參數、授權令牌等資訊都是快取的，也就是說配置一次，下次再打開的時候也是默認存在的。

5、全局參數配置

對於一些全局的參數，比如請求頭中需要攜帶請求客戶端、版本號等資訊，可以在全局參數中配置，如下：

總結

本篇文章介紹了微服務集成網關聚合Swagger文檔，開發中非常實用。

Tags: 微服務 Spring Cloud