Swagger Butler是一個(gè)基于Swagger與Zuul構(gòu)建的API文檔匯集工具。通過構(gòu)建一個(gè)簡(jiǎn)單的Spring Boot應(yīng)用，增加一些配置就能將現(xiàn)有整合了Swagger的Web應(yīng)用的API文檔都匯總到一起，方便查看與測(cè)試。

項(xiàng)目地址

• Github：https://github.com/dyc87112/swagger-butler
• Gitee：https://gitee.com/didispace/swagger-butler

使用手冊(cè)

快速入門

該工具的時(shí)候非常簡(jiǎn)單，先通過下面幾步簡(jiǎn)單入門：

第一步：構(gòu)建一個(gè)基礎(chǔ)的Spring Boot應(yīng)用

如您還不知道如何創(chuàng)建Spring Boot應(yīng)用，可以先閱讀本篇入門文章

第二步：在pom.xml中引入依賴

<parent>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-parent</artifactId>
 <version>1.5.10.RELEASE</version>
</parent>
<dependencies>
 <dependency>
 <groupId>com.didispace</groupId>
 <artifactId>swagger-butler-core</artifactId>
 <version>1.0.0</version>
 </dependency>
</dependencies>

第三步：創(chuàng)建應(yīng)用主類，增加@EnableSwaggerButler注解開啟Swagger Butler功能

@EnableSwaggerButler
@SpringBootApplication
public class StaticApplication {
 public static void main(String[] args) {
 SpringApplication.run(StaticApplication.class);
 }
}

第四步：配置文件中增加Swagger文檔的地址配置

spring.application.name=swagger-butler-example-static
server.port=11000
zuul.routes.service-a.path=/service-a/**
zuul.routes.service-a.url=http://localhost:10010/
swagger.butler.resources[0].name=service-a
swagger.butler.resources[0].url=/service-a/v2/api-docs
swagger.butler.resources[0].swagger-version=2.0
zuul.routes.service-b.path=/service-b/**
zuul.routes.service-b.url=http://localhost:10020/
swagger.butler.resources[1].name=service-b
swagger.butler.resources[1].url=/service-b/v2/api-docs
swagger.butler.resources[1].swagger-version=2.0

上面配置了兩個(gè)文檔位置，由于這里還沒有引入服務(wù)發(fā)現(xiàn)機(jī)制，所以需要先用zuul來配置訪問本應(yīng)用請(qǐng)求被轉(zhuǎn)發(fā)到具體服務(wù)的路由規(guī)則。然后在配置resource信息指向具體的獲取swagger的json配置文檔的接口鏈接。

第五步：訪問http://localhost:11000/swagger-ui.html

Example

代碼示例具體可見swagger-butler-example-static目錄

原理可見：Spring Cloud Zuul中使用Swagger匯總API接口文檔

與eureka整合

在整合eureka獲取所有該注冊(cè)中心下的API文檔時(shí)，只需要在上面工程的基礎(chǔ)上增加下面的配置：

第一步：pom.xml中增加eureka依賴，比如：

<dependencies>
 <dependency>
 <groupId>com.didispace</groupId>
 <artifactId>swagger-butler-core</artifactId>
 <version>1.0.0</version>
 </dependency>
 <dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-eureka</artifactId>
 <version>1.3.2.RELEASE</version>
 </dependency>
</dependencies>

第二步：應(yīng)用主類增加@EnableDiscoveryClient，比如：

@EnableDiscoveryClient
@EnableSwaggerButler
@SpringBootApplication
public class EurekaApplication {
 public static void main(String[] args) {
 SpringApplication.run(EurekaApplication.class);
 }
}

第三步：配置文件中增加eureka的配置，比如：

spring.application.name=swagger-butler-example-eureka
server.port=11001
eureka.client.service-url.defaultZone=http://eureka.didispace.com/eureka/

代碼示例具體可見swagger-butler-example-eureka目錄

與consul整合

在整合eureka獲取所有該注冊(cè)中心下的API文檔時(shí)，只需要在上面工程的基礎(chǔ)上增加下面的配置：

第一步：pom.xml中增加consul依賴，比如：

<dependencies>
 <dependency>
 <groupId>com.didispace</groupId>
 <artifactId>swagger-butler-core</artifactId>
 <version>1.0.0</version>
 </dependency>
 <dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-consul-discovery</artifactId>
 <version>1.3.2.RELEASE</version>
 </dependency>
</dependencies>

第二步：應(yīng)用主類增加@EnableDiscoveryClient，比如：

@EnableDiscoveryClient
@EnableSwaggerButler
@SpringBootApplication
public class EurekaApplication {
 public static void main(String[] args) {
 SpringApplication.run(EurekaApplication.class);
 }
}

第三步：配置文件中增加eureka的配置，比如：

spring.application.name=swagger-butler-example-consul
server.port=11002
spring.cloud.consul.host=localhost
spring.cloud.consul.port=8500

代碼示例具體可見swagger-butler-example-consul目錄