摘要：代碼示例本文示例讀者可以通過查看下面倉庫的中的三個項目如果您對這些感興趣，歡迎收藏轉發給予支持以下專題教程也許您會有興趣基礎教程基礎教程

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

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

Spring Cloud構建微服務架構：服務網關（基礎）

Spring Boot中使用Swagger2構建強大的RESTful API文檔

本文首發于：http://blog.didispace.com/Spr...

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

下面只詳細描述一個服務的構建內容，另外一個只是名稱不同，如有疑問可以在文末查看詳細的代碼樣例。

第一步：構建一個基礎的Spring Boot應用，在pom.xml中引入eureka的依賴、web模塊的依賴以及swagger的依賴（這里使用了我們自己構建的starter，詳細可點擊查看）。主要內容如下：

    org.springframework.boot
    spring-boot-starter-parent
    1.5.10.RELEASE
    



    
        org.springframework.cloud
        spring-cloud-starter-eureka
    

    
        org.springframework.boot
        spring-boot-starter-web
    

    
        com.spring4all
        swagger-spring-boot-starter
        1.7.0.RELEASE
    



    
        
            org.springframework.cloud
            spring-cloud-dependencies
            Dalston.SR1
            pom
            import
        
    

第二步：編寫應用主類：

@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服務可以如法炮制，不再贅述。

在Spring Cloud構建微服務架構：服務網關（基礎）一文中，已經非常詳細的介紹過使用Spring Cloud Zuul構建網關的詳細步驟，這里主要介紹在基礎網關之后，如何整合Swagger來匯總這些API文檔。

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

    org.springframework.cloud
    spring-cloud-starter-zuul


    org.springframework.cloud
    spring-cloud-starter-eureka


    com.spring4all
    swagger-spring-boot-starter
    1.7.0.RELEASE

第二步：在應用主類中配置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 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文檔，從而實現匯總加載內容。

將上面構建的兩個微服務以及API網關都啟動起來之后，訪問網關的swagger頁面，比如：http://localhost:11000/swagger-ui.html，此時可以看到如下圖所示的內容：

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

本文示例讀者可以通過查看下面倉庫的中的swagger-service-a、swagger-service-b、swagger-api-gateway三個項目：

Github

Gitee

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

以下專題教程也許您會有興趣

Spring Boot基礎教程

Spring Cloud基礎教程