有很多讀者問過這樣的一個問題：雖然使用Swagger可以為Spring MVC編寫的介面生成了API文件，但是在微服務化之後，這些API文件都離散在各個微服務中，是否有辦法將這些介面都整合到一個文件中？之前給大家的回覆都只是簡單的說了個思路，昨天正好又有人問起，索性就舉個例子寫成博文供大家參考吧。
如果您還不瞭解Spring Cloud Zuul和Swagger，建議優先閱讀下面兩篇，有一個初步的瞭解：
準備工作
上面說了問題的場景是在微服務化之後，所以我們需要先構建兩個簡單的基於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，大家可以通過eureka.didispace.com/檢視詳細以及使用方法。另外，swagger.base-package引數制定了要生成文件的package，只有com.didispace包下的Controller才會被生成文件。
注意：上面構建了swagger-service-a服務，swagger-service-b服務可以如法炮製，不再贅述。
構建API閘道器並整合Swagger
在Spring Cloud構建微服務架構：服務閘道器（基礎）一文中，已經非常詳細的介紹過使用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文件，從而實現彙總載入內容。
測試驗證
將上面構建的兩個微服務以及API閘道器都啟動起來之後，訪問閘道器的swagger頁面，比如：http://localhost:11000/swagger-ui.html，此時可以看到如下圖所示的內容：
可以看到在分組選擇中就是當前配置的兩個服務的選項，選擇對應的服務名之後就會展示該服務的API文件內容。
程式碼示例
本文示例讀者可以通過檢視下面倉庫的中的swagger-service-a、swagger-service-b、swagger-api-gateway三個專案：
如果您對這些感興趣，歡迎star、follow、收藏、轉發給予支援！
開源專案
針對本文開發一個簡化的開源專案，歡迎Star支援：swagger-butler