微服務如何聚合 API 文件?這波秀~

bucaichenmou發表於2022-02-14

今天這篇文章介紹一下微服務如何聚合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的配置其實很簡單,分為如下部分:

  1. API文件基本資訊配置
  2. 授權資訊配置(基於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文件,開發中非常實用。

相關文章