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

時間 2019-11-16

標籤 spring cloud zuul 使用 swagger 彙總 api 接口文檔欄目 Spring 简体版

原文原文鏈接

有不少讀者問過這樣的一個問題：雖然使用Swagger能夠爲Spring MVC編寫的接口生成了API文檔，可是在微服務化以後，這些API文檔都離散在各個微服務中，是否有辦法將這些接口都整合到一個文檔中？以前給你們的回覆都只是簡單的說了個思路，昨天正好又有人問起，索性就舉個例子寫成博文供你們參考吧。html

若是您還不瞭解Spring Cloud Zuul和Swagger，建議優先閱讀下面兩篇，有一個初步的瞭解：java

準備工做

上面說了問題的場景是在微服務化以後，因此咱們須要先構建兩個簡單的基於Spring Cloud的微服務，命名爲swagger-service-a和swagger-service-b。git

下面只詳細描述一個服務的構建內容，另一個只是名稱不一樣，若有疑問能夠在文末查看詳細的代碼樣例。github

第一步：構建一個基礎的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接口，用來後續在文檔中查看使用。web

第三步：設置配置文件內容：

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，你們能夠經過eureka.didispace.com/查看詳細以及使用方法。另外，swagger.base-package參數制定了要生成文檔的package，只有com.didispace包下的Controller纔會被生成文檔。spring

注意：上面構建了swagger-service-a服務，swagger-service-b服務能夠如法炮製，再也不贅述。api

構建API網關並整合Swagger

在Spring Cloud構建微服務架構：服務網關（基礎）一文中，已經很是詳細的介紹過使用Spring Cloud Zuul構建網關的詳細步驟，這裏主要介紹在基礎網關以後，如何整合Swagger來彙總這些API文檔。springboot

第一步：在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文檔，從而實現彙總加載內容。架構