Spring Cloud Zuul中使用Swagger彙總API接口文檔

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

如果您還不了解

Spring Cloud Zuul

和

Swagger

，建議優先閱讀下面兩篇，有一個初步的了解：

• Spring Cloud建構微服務架構：服務網關（基礎）
• Spring Boot中使用Swagger2建構強大的RESTful API文檔

https://blog.didispace.com/Spring-Cloud-Zuul-use-Swagger-API-doc/#%E5%87%86%E5%A4%87%E5%B7%A5%E4%BD%9C 準備工作

上面說了問題的場景是在微服務化之後，是以我們需要先建構兩個簡單的基于Spring Cloud的微服務，命名為

swagger-service-a

swagger-service-b

。

下面隻較長的描述一個服務的建構内容，另外一個隻是名稱不同，如有疑問可以在文末檢視詳細的代碼樣例。

• 第一步：建構一個基礎的Spring Boot應用，在

  pom.xml

  中引入eureka的依賴、web子產品的依賴以及swagger的依賴（這裡使用了我們自己建構的starter， 詳細可點選檢視 ）。主要内容如下：

<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>      

• 第二步：編寫應用主類：

@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中提供的自定義注解，通過該注解會初始化預設的Swagger文檔設定。下面還建立了一個通過Spring MVC編寫的HTTP接口，用來後續在文檔中檢視使用。

• 第三步：設定配置檔案内容：

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

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

swagger.base-package=com.didispace      

其中，eureka服務端的配置采用了本站的公益eureka，大家可以通過

http://eureka.didispace.com/

檢視詳細以及使用方法。另外，

swagger.base-package

參數制定了要生成文檔的package，隻有

com.didispace

包下的Controller才會被生成文檔。

注意：上面建構了swagger-service-a服務，swagger-service-b服務可以如法炮制，不再贅述。

https://blog.didispace.com/Spring-Cloud-Zuul-use-Swagger-API-doc/#%E6%9E%84%E5%BB%BAAPI%E7%BD%91%E5%85%B3%E5%B9%B6%E6%95%B4%E5%90%88Swagger 建構API網關并整合Swagger

在

一文中，已經非常詳細的介紹過使用Spring Cloud Zuul建構網關的詳細步驟，這裡主要介紹在基礎網關之後，如何整合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>      

• 第二步：在應用主類中配置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功能的注解。這裡的核心是下面對

SwaggerResourcesProvider

的接口實作部分，通過

SwaggerResource

添加了多個文檔來源，按上面的配置，網關上Swagger會通過通路

/swagger-service-a/v2/api-docs

swagger-service-b/v2/api-docs

來加載兩個文檔内容，同時由于目前應用是Zuul建構的API網關，這兩個請求會被轉發到

swagger-service-a

swagger-service-b

服務上的

/v2/api-docs

接口獲得到Swagger的JSON文檔，進而實作彙總加載内容。

https://blog.didispace.com/Spring-Cloud-Zuul-use-Swagger-API-doc/#%E6%B5%8B%E8%AF%95%E9%AA%8C%E8%AF%81 測試驗證

将上面建構的兩個微服務以及API網關都啟動起來之後，通路網關的swagger頁面，比如：

http://localhost:11000/swagger-ui.html

，此時可以看到如下圖所示的内容：

可以看到在分組選擇中就是目前配置的兩個服務的選項，選擇對應的服務名之後就會展示該服務的API文檔内容。

https://blog.didispace.com/Spring-Cloud-Zuul-use-Swagger-API-doc/#%E4%BB%A3%E7%A0%81%E7%A4%BA%E4%BE%8B 代碼示例

本文示例讀者可以通過檢視下面倉庫的中的

swagger-service-a

、

swagger-service-b

swagger-api-gateway

三個項目：

• Github
• Gitee

如果您對這些感興趣，歡迎star、follow、收藏、轉發給予支援！

https://blog.didispace.com/Spring-Cloud-Zuul-use-Swagger-API-doc/#%E4%BB%A5%E4%B8%8B%E4%B8%93%E9%A2%98%E6%95%99%E7%A8%8B%E4%B9%9F%E8%AE%B8%E6%82%A8%E4%BC%9A%E6%9C%89%E5%85%B4%E8%B6%A3 以下專題教程也許您會有興趣

• Spring Boot基礎教程
• Spring Cloud基礎教程