有很多讀者問過這樣的一個(gè)問題：雖然使用Swagger可以為Spring MVC編寫的接口生成了API文檔，但是在微服務(wù)化之后，這些API文檔都離散在各個(gè)微服務(wù)中，是否有辦法將這些接口都整合到一個(gè)文檔中？之前給大家的回復(fù)都只是簡單的說了個(gè)思路，昨天正好又有人問起，索性就舉個(gè)例子寫成博文供大家參考吧。

如果您還不了解Spring Cloud Zuul和Swagger，建議優(yōu)先閱讀下面兩篇，有一個(gè)初步的了解：

• Spring Cloud構(gòu)建微服務(wù)架構(gòu)：服務(wù)網(wǎng)關(guān)（基礎(chǔ)）
• Spring Boot中使用Swagger2構(gòu)建強(qiáng)大的RESTful API文檔

本文首發(fā)于：http://blog.didispace.com/Spring-Cloud-Zuul-use-Swagger-API-doc/

準(zhǔn)備工作

上面說了問題的場(chǎng)景是在微服務(wù)化之后，所以我們需要先構(gòu)建兩個(gè)簡單的基于Spring Cloud的微服務(wù)，命名為swagger-service-a和swagger-service-b。

下面只詳細(xì)描述一個(gè)服務(wù)的構(gòu)建內(nèi)容，另外一個(gè)只是名稱不同，如有疑問可以在文末查看詳細(xì)的代碼樣例。

• 第一步：構(gòu)建一個(gè)基礎(chǔ)的Spring Boot應(yīng)用，在pom.xml中引入eureka的依賴、web模塊的依賴以及swagger的依賴（這里使用了我們自己構(gòu)建的starter，詳細(xì)可點(diǎn)擊查看）。主要內(nèi)容如下：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.5.10.RELEASE</version>
    <relativePath/>
</parent>

<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-eureka</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>com.spring4all</groupId>
        <artifactId>swagger-spring-boot-starter</artifactId>
        <version>1.7.0.RELEASE</version>
    </dependency>
</dependencies>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>Dalston.SR1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

• 第二步：編寫應(yīng)用主類：

@EnableSwagger2Doc
@EnableDiscoveryClient
@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        new SpringApplicationBuilder(Application.class).web(true).run(args);
    }

    @RestController
    class AaaController {
        @Autowired
        DiscoveryClient discoveryClient;

        @GetMapping("/service-a")
        public String dc() {
            String services = "Services: " + discoveryClient.getServices();
            System.out.println(services);
            return services;
        }
    }
}

其中，@EnableSwagger2Doc注解是我們自制Swagger Starter中提供的自定義注解，通過該注解會(huì)初始化默認(rèn)的Swagger文檔設(shè)置。下面還創(chuàng)建了一個(gè)通過Spring MVC編寫的HTTP接口，用來后續(xù)在文檔中查看使用。

• 第三步：設(shè)置配置文件內(nèi)容：

spring.application.name=swagger-service-a
server.port=10010

eureka.client.serviceUrl.defaultZone=http://eureka.didispace.com/eureka/

swagger.base-package=com.didispace

其中，eureka服務(wù)端的配置采用了本站的公益eureka，大家可以通過http://eureka.didispace.com/查看詳細(xì)以及使用方法。另外，swagger.base-package參數(shù)制定了要生成文檔的package，只有com.didispace包下的Controller才會(huì)被生成文檔。

注意：上面構(gòu)建了swagger-service-a服務(wù)，swagger-service-b服務(wù)可以如法炮制，不再贅述。

構(gòu)建API網(wǎng)關(guān)并整合Swagger

在Spring Cloud構(gòu)建微服務(wù)架構(gòu)：服務(wù)網(wǎng)關(guān)（基礎(chǔ)）一文中，已經(jīng)非常詳細(xì)的介紹過使用Spring Cloud Zuul構(gòu)建網(wǎng)關(guān)的詳細(xì)步驟，這里主要介紹在基礎(chǔ)網(wǎng)關(guān)之后，如何整合Swagger來匯總這些API文檔。

• 第一步：在pom.xml中引入swagger的依賴，這里同樣使用了我們自制的starter，所以主要的依賴包含下面這些：

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-zuul</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-eureka</artifactId>
</dependency>
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.7.0.RELEASE</version>
</dependency>

• 第二步：在應(yīng)用主類中配置swagger，具體如下：

@EnableSwagger2Doc
@EnableZuulProxy
@SpringCloudApplication
public class Application {

    public static void main(String[] args) {
        new SpringApplicationBuilder(Application.class).web(true).run(args);
    }

    @Component
    @Primary
    class DocumentationConfig implements SwaggerResourcesProvider {
        @Override
        public List<SwaggerResource> get() {
            List resources = new ArrayList<>();
            resources.add(swaggerResource("service-a", "/swagger-service-a/v2/api-docs", "2.0"));
            resources.add(swaggerResource("service-b", "/swagger-service-b/v2/api-docs", "2.0"));
            return resources;
        }

        private SwaggerResource swaggerResource(String name, String location, String version) {
            SwaggerResource swaggerResource = new SwaggerResource();
            swaggerResource.setName(name);
            swaggerResource.setLocation(location);
            swaggerResource.setSwaggerVersion(version);
            return swaggerResource;
        }
    }
}

說明：@EnableSwagger2Doc上面說過是開啟Swagger功能的注解。這里的核心是下面對(duì)SwaggerResourcesProvider的接口實(shí)現(xiàn)部分，通過SwaggerResource添加了多個(gè)文檔來源，按上面的配置，網(wǎng)關(guān)上Swagger會(huì)通過訪問/swagger-service-a/v2/api-docs和swagger-service-b/v2/api-docs來加載兩個(gè)文檔內(nèi)容，同時(shí)由于當(dāng)前應(yīng)用是Zuul構(gòu)建的API網(wǎng)關(guān)，這兩個(gè)請(qǐng)求會(huì)被轉(zhuǎn)發(fā)到swagger-service-a和swagger-service-b服務(wù)上的/v2/api-docs接口獲得到Swagger的JSON文檔，從而實(shí)現(xiàn)匯總加載內(nèi)容。

測(cè)試驗(yàn)證

將上面構(gòu)建的兩個(gè)微服務(wù)以及API網(wǎng)關(guān)都啟動(dòng)起來之后，訪問網(wǎng)關(guān)的swagger頁面，比如：http://localhost:11000/swagger-ui.html，此時(shí)可以看到如下圖所示的內(nèi)容：

Spring-Cloud-Zuul-use-Swagger-API-doc-1.png

可以看到在分組選擇中就是當(dāng)前配置的兩個(gè)服務(wù)的選項(xiàng)，選擇對(duì)應(yīng)的服務(wù)名之后就會(huì)展示該服務(wù)的API文檔內(nèi)容。

代碼示例

本文示例讀者可以通過查看下面?zhèn)}庫的中的swagger-service-a、swagger-service-b、swagger-api-gateway三個(gè)項(xiàng)目：

• Github
• Gitee

如果您對(duì)這些感興趣，歡迎star、follow、收藏、轉(zhuǎn)發(fā)給予支持！

以下專題教程也許您會(huì)有興趣

• Spring Boot基礎(chǔ)教程
• Spring Cloud基礎(chǔ)教程