有很多讀者問過這樣的一個問題:雖然使用Swagger可以爲Spring MVC編寫的接口生成了API文檔,但是在微服務化之後,這些API文檔都離散在各個微服務中,是否有辦法將這些接口都整合到一個文檔中?之前給大家的回覆都只是簡單的說了個思路,昨天正好又有人問起,索性就舉個例子寫成博文供大家參考吧。
如果您還不瞭解Spring Cloud Zuul
和Swagger
,建議優先閱讀下面兩篇,有一個初步的瞭解:
本文首發於:http://blog.didispace.com/Spring-Cloud-Zuul-use-Swagger-API-doc/
準備工作
上面說了問題的場景是在微服務化之後,所以我們需要先構建兩個簡單的基於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服務可以如法炮製,不再贅述。
構建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、收藏、轉發給予支持!