今天這篇文章介紹一下微服務(wù)如何聚合Swagger實(shí)現(xiàn)接口文檔管理。

文章目錄如下：

為什么需要聚合?

微服務(wù)模塊眾多，如果不聚合文檔，則訪(fǎng)問(wèn)每個(gè)服務(wù)的API文檔都需要單獨(dú)訪(fǎng)問(wèn)一個(gè)Swagger UI界面，這么做客戶(hù)端能否接受?

反正作為強(qiáng)迫癥的我是接受不了.......

既然使用了微服務(wù)，就應(yīng)該有統(tǒng)一的API文檔入口。

如何聚合?

統(tǒng)一的文檔入口顯然應(yīng)該聚合到網(wǎng)關(guān)中，通過(guò)網(wǎng)關(guān)的入口統(tǒng)一映射到各個(gè)模塊。

演示

本文采用Spring Cloud Gateway 聚合 Swagger的 方式 生成API文檔。

案例源碼結(jié)構(gòu)如下：

本文只介紹如何聚合Swagger，關(guān)于網(wǎng)關(guān)、注冊(cè)中心等內(nèi)容不再介紹，有不了解的看陳某前面文章。

單個(gè)服務(wù)如何聚合Swagger?

這里的單個(gè)服務(wù)不包括網(wǎng)關(guān)，網(wǎng)關(guān)需要單獨(dú)配置。

單個(gè)服務(wù)聚合其實(shí)很簡(jiǎn)單，就是普通的Spring Boot 整合 Swagger，但是微服務(wù)模塊眾多，不能每個(gè)微服都整合一番，因此可以自定義一個(gè)swagger-starter，之后每個(gè)微服務(wù)都依賴(lài)這個(gè)starter即可。

詳細(xì)的步驟如下：

1、創(chuàng)建swagger-starter

自定義starter這里就不再介紹了，都是基礎(chǔ)的知識(shí);

目錄結(jié)構(gòu)如下：

1）添加依賴(lài)

對(duì)于Swagger原生的UI界面陳某不太喜歡，因此使用了一款看起來(lái)還不錯(cuò)的UI界面，依賴(lài)如下：

<!--swagger-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-boot-starter</artifactId>
</dependency>

<!--swagger-ui  這里是用了一個(gè)好看一點(diǎn)ui界面-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
</dependency>

對(duì)于UI界面，每個(gè)人審美不同，選擇自己喜歡的就好。

2）自動(dòng)配置類(lèi)配置Swagger

陳某是將每個(gè)服務(wù)的API信息抽離出一個(gè)屬性類(lèi)SwaggerProperties，后續(xù)只需要在每個(gè)服務(wù)的配置文件中指定即可。

@Data
@ConfigurationProperties(prefix = SwaggerProperties.PREFIX)
@Component
@EnableConfigurationProperties
public class SwaggerProperties {
    public static final String PREFIX="spring.swagger";

    //包
    private String basePackage;

    //作者相關(guān)信息
    private Author author;

    //API的相關(guān)信息
    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;
    }
}

對(duì)于Swagger的配置其實(shí)很簡(jiǎn)單，分為如下部分：

• API文檔基本信息配置
• 授權(quán)信息配置(基于OAuth2的認(rèn)證配置)

API文檔配置無(wú)非就是配置文檔的基本信息，比如文檔標(biāo)題、作者、聯(lián)系方式.....

代碼如下：

授權(quán)信息配置也很簡(jiǎn)單，就是在全局信息的請(qǐng)求頭中配置一個(gè)能夠放置令牌的地方，代碼如下：

此處對(duì)應(yīng)UI界面的地方如下圖：

只需要將獲取token令牌設(shè)置到這里即可。

好了，swagger-starter關(guān)鍵代碼就介紹完了，詳細(xì)配置見(jiàn)源碼。

2、微服務(wù)引用swagger-starter

單個(gè)微服務(wù)引用就很簡(jiǎn)單了，只需要添加如下依賴(lài)：

@Data
@ConfigurationProperties(prefix = SwaggerProperties.PREFIX)
@Component
@EnableConfigurationProperties
public class SwaggerProperties {
    public static final String PREFIX="spring.swagger";

    //包
    private String basePackage;

    //作者相關(guān)信息
    private Author author;

    //API的相關(guān)信息
    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;
    }
}

接下來(lái)只需要在配置文件配置API相關(guān)的信息即可，比如訂單服務(wù)的配置如下：

好了，至此單個(gè)服務(wù)的配置完成了。

此時(shí)我們可以驗(yàn)證一下，直接訪(fǎng)問(wèn)：http://localhost:3002/swagger-order-boot/v2/api-docs，結(jié)果如下圖：

網(wǎng)關(guān)如何聚合Swagger?

網(wǎng)關(guān)聚合的思想很簡(jiǎn)單，就是從路由中獲取微服務(wù)的訪(fǎng)問(wèn)地址，然后拼接上 /v2/api-docs 即可。

同樣的還是要添加Swagger的兩個(gè)依賴(lài)，如下：

<!--swagger-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-boot-starter</artifactId>
</dependency>

<!--swagger-ui  這里是用了一個(gè)好看一點(diǎn)ui界面-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
</dependency>

創(chuàng)建GatewaySwaggerResourcesProvider實(shí)現(xiàn)SwaggerResourcesProvider，重寫(xiě)其中的get方法，代碼如下：

”好了，網(wǎng)關(guān)的配置這里就完成了。

此時(shí)啟動(dòng)網(wǎng)關(guān)、訂單、庫(kù)存服務(wù)，直接訪(fǎng)問(wèn)網(wǎng)關(guān)的文檔：http://localhost:3001/doc.html，結(jié)果如下圖：

API文檔好用的功能介紹

不得不說(shuō)這款Swagger UI 界面還是比較簡(jiǎn)單易用的，個(gè)人用起來(lái)還不錯(cuò)。

1、搜索功能

在右上角的搜索功能可以根據(jù)接口描述搜索相關(guān)的接口信息，如下圖：

2、離線(xiàn)文檔

可以直接拷貝文檔的MarkDown形式轉(zhuǎn)換成Html或者PDF生成離線(xiàn)文檔，如下圖：

3、令牌配置

在訪(fǎng)問(wèn)需要認(rèn)證的接口時(shí)，可以通過(guò)配置令牌，這樣令牌將會(huì)全局生效，不必每個(gè)請(qǐng)求都要配置一遍，如下：

4、配置緩存

該文檔的所有配置，包括請(qǐng)求參數(shù)、授權(quán)令牌等信息都是緩存的，也就是說(shuō)配置一次，下次再打開(kāi)的時(shí)候也是默認(rèn)存在的。

5、全局參數(shù)配置

對(duì)于一些全局的參數(shù)，比如請(qǐng)求頭中需要攜帶請(qǐng)求客戶(hù)端、版本號(hào)等信息，可以在全局參數(shù)中配置，如下：

總結(jié)

本篇文章介紹了微服務(wù)集成網(wǎng)關(guān)聚合Swagger文檔，開(kāi)發(fā)中非常實(shí)用。