有很多讀者問過這樣的一個問題：

雖然使用Swagger可以為Spring MVC編寫的介面生成了API文件，但是在微服務化之後，這些API文件都離散在各個微服務中，是否有辦法將這些介面都整合到一個文件中？

之前給大家的回覆都只是簡單的說了個思路，昨天正好又有人問起，索性就舉個例子寫成博文供大家參考吧。

如果你還不瞭解 SpringCloudZuul和 Swagger，建議優先閱讀下面兩篇，有一個初步的瞭解：

1、準備工作

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

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

• 第一步：構建一個基礎的Spring Boot應用，在 pom.xml中引入eureka的依賴、web模組的依賴以及swagger的依賴（這裡使用了我們自己構建的starter，詳細可點選檢視）。

  主要內容如下：

1. <parent>

2. <groupId>org.springframework.boot</groupId>

3. <artifactId>spring-boot-starter-parent</artifactId>

4. <version>1.5.10.RELEASE

   </version>

5. <relativePath/>

6. </parent>

7. <dependencies>

8. <dependency>

9. <groupId>org.springframework.cloud</groupId>

10. <artifactId>spring-cloud-starter-eureka</artifactId>

11. </dependency>

12. <dependency>

13. <groupId>org.springframework.boot</groupId>

14. <artifactId>

    spring-boot-starter-web</artifactId>

15. </dependency>

16. <dependency>

17. <groupId>com.spring4all</groupId>

18. <artifactId>swagger-spring-boot-starter</artifactId>

19. <version>1.7.0.RELEASE</version>

20. </dependency>

21. </dependencies>

22. <dependencyManagement>

23. <dependencies>

24. <dependency>

25. <groupId>org.springframework.cloud</groupId>

26. <artifactId>spring-cloud-dependencies</artifactId>

27. <version>Dalston.SR1</version>

28. <type>pom</type>

29. <scope>import</scope>

30. </dependency>

31. </dependencies>

32. </dependencyManagement>

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

1. @EnableSwagger2Doc

2. @EnableDiscoveryClient

3. @SpringBootApplication

4. publicclassApplication {

5. publicstaticvoid main(String[] args) {

6. newSpringApplicationBuilder(Application.class).web(true).run(args);

7.    }

8. @RestController

9. classAaaController {

10. @Autowired

11. DiscoveryClient discoveryClient;

12. @GetMapping("/service-a")

13. publicString dc() {

14. String services = "Services: " + discoveryClient.getServices();

15. System.out.println(services);

16. return services;

17.        }

18.    }

19. }

其中， @EnableSwagger2Doc註解是我們自制Swagger Starter中提供的自定義註解，通過該註解會初始化預設的Swagger文件設定。下面還建立了一個通過Spring MVC編寫的HTTP介面，用來後續在文件中檢視使用。

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

1. spring.application.name=swagger-service-a

2. server.port=10010

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

4. swagger.base-package=com.didispace

其中，eureka服務端的配置採用了本站的公益eureka，大家可以通過http://eureka.didispace.com/檢視詳細以及使用方法。另外， swagger.base-package引數制定了要生成文件的package，只有 com.didispace包下的Controller才會被生成文件。

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

2、構建API閘道器並整合Swagger

在Spring Cloud構建微服務架構：服務閘道器（基礎）一文中，已經非常詳細的介紹過使用Spring Cloud Zuul構建閘道器的詳細步驟，這裡主要介紹在基礎閘道器之後，如何整合Swagger來彙總這些API文件。

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

1. <dependency>

2. <groupId>org.springframework.cloud</groupId>

3. <artifactId>spring-cloud-starter-zuul</artifactId>

4. </dependency>

5. <dependency>

6. <groupId>org.springframework.cloud</groupId>

7. <artifactId>spring-cloud-starter-eureka</artifactId>

8. </dependency>

9. <dependency>

10. <groupId>com.spring4all</groupId>

11. <artifactId>swagger-spring-boot-starter</artifactId>

12. <version>1.7.0.RELEASE</version>

13. </dependency>

• 第二步：在應用主類中配置swagger，具體如下：

1. @EnableSwagger2Doc

2. @EnableZuulProxy

3. @SpringCloudApplication

4. publicclassApplication {

5. publicstaticvoid main(String[] args) {

6. newSpringApplicationBuilder(Application.class).web(true).run(args);

7.    }

8. @Component

9. @Primary

10. classDocumentationConfigimplementsSwaggerResourcesProvider {

11. @Override

12. publicList<SwaggerResource> get() {

13. List resources = newArrayList<>();

14.            resources.add(swaggerResource("service-a", "/swagger-service-a/v2/api-docs", "2.0"));

15.            resources.add(swaggerResource("service-b", "/swagger-service-b/v2/api-docs", "2.0"));

16. return resources;

17.        }

18. privateSwaggerResource swaggerResource(String name, String location, String version) {

19. SwaggerResource swaggerResource = newSwaggerResource();

20.            swaggerResource.setName(name);

21.            swaggerResource.setLocation(location);

22.            swaggerResource.setSwaggerVersion(version);

23. return swaggerResource;

24.        }

25.    }

26. }

說明： @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文件，從而實現彙總載入內容。

3、測試驗證

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

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

5、程式碼示例

本文示例讀者可以通過檢視下面倉庫的中的 swagger-service-a、 swagger-service-b、 swagger-api-gateway三個專案：

• Github：

  https://github.com/dyc87112/SpringCloud-Learning/tree/master/2-Dalston%E7%89%88%E6%95%99%E7%A8%8B%E7%A4%BA%E4%BE%8B/

• Gitee：

  https://gitee.com/didispace/SpringCloud-Learning/tree/master/2-Dalston%E7%89%88%E6%95%99%E7%A8%8B%E7%A4%BA%E4%BE%8B

除了本文的方法之外，我還開發了一個開源專案，您也可以直接來使用，歡迎Star支援：https://github.com/dyc87112/swagger-butler

最後再給大家推薦一個《零基礎學Python》的視訊課程。

Python這門程式設計，我是非常推薦大家要去掌握的，由於該課程屬於基礎類課程，所以一些非計算機專業的朋友也可以去嘗試學習和應用。因為它比起Java來說它更容易上手，通過一些基礎知識內容就可以幫助減輕一些日常工作繁瑣的事情，讓你能夠事半功倍。加上現在爬蟲、AI等框架的發展，如果你有足夠的積極性和想象空間，可以玩的內容會越來越多，所以我把這個專欄推薦給你，希望你可以喜歡並有所收穫！

- END -

 往期推薦：

• 死磕Java系列：

……

• Spring系列：

……

可關注我的公眾號

深入交流、更多福利

掃碼加入我的知識星球

點選“閱讀原文”，看本號其他精彩內容