Swagger Butler是一个基于Swagger与Zuul构建的API文档汇集工具。通过构建一个简单的Spring Boot应用，增加一些配置就能将现有整合了Swagger的Web应用的API文档都汇总到一起，方便查看与测试。
项目地址
快速入门
该工具的时候非常简单，先通过下面几步简单入门：
第一步：构建一个基础的Spring Boot应用
如您还不知道如何创建Spring Boot应用，可以先阅读本篇入门文章
第二步：在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.1.0</version> </dependency> </dependencies>
第三步：创建应用主类，增加@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 # default config swagger.butler.api-docs-path=/v2/api-docs swagger.butler.swagger-version=2.0 # swagger resource zuul.routes.user.path=/service-a/** zuul.routes.user.url=http://localhost:10010/ swagger.butler.resources.user.name=user-service # swagger resource zuul.routes.product.path=/service-b/** zuul.routes.product.url=http://localhost:10020/ swagger.butler.resources.product.name=product-service swagger.butler.resources.product.api-docs-path=/xxx/v2/api-docs swagger.butler.resources.product.swagger-version=2.0
上面配置了两个文档位置，由于这里还没有引入服务发现机制，所以Zuul的路由需要我们自己配置。然后在配置resource信息的时候，从1.1.0版本开始做了较大的调整，由于具体的访问路径是可以通过路由信息产生的，所以对于resource的配置信息只关注三个内容：
name：API文档在swagger中展现名称api-docs-path：要获取的swagger文档的具体路径；如果不配置会使用全局的swagger.butler.api-docs-path配置，默认为/v2/api-docs。；这里的配置主要用户一些特殊情况，比如服务自身设置了context-path，或者修改了swagger默认的文档路径swagger-version：swagger版本信息；如果不配置会使用全局的swagger.butler.swagger-version配置，默认为2.0。
第五步：访问http://localhost:11000/swagger-ui.html
代码示例具体可见
swagger-butler-example-static目录
Zuul的路由与SwaggerResources配置之间的关系
如上示例中<route-name>展示了Zuul的路由名称与SwaggerResources配置之间的关联关系
zuul.routes.<route-name>.path=/service-b/** zuul.routes.<route-name>.url=http://localhost:10020/ swagger.butler.resources.<route-name>.name=product-service swagger.butler.resources.<route-name>.api-docs-path=/xxx/v2/api-docs swagger.butler.resources.<route-name>.swagger-version=2.0
注意：在没有使用自动配置或整合服务治理的时候，要生成Swagger文档的时候，resources信息中的name属性是必须配置的，api-docs-path和swagger-version不配置的时候会使用默认的全局配置
全局配置
对于Swagger文档获取的全局配置内容，目前主要包含下面几个参数：
swagger.butler.api-docs-path=/v2/api-docs swagger.butler.swagger-version=2.0
使用Zuul中的路由自动配置（新特性）
在快速入门示例中我们配置了两个路由信息，同时为这两个路由信息配置了对应的Swagger信息来获取API文档详情，从1.1.0版本开始，增加了几个通过Zuul的路由配置来自动生成文档信息的参数，这样可以减少快速入门示例中那些繁琐的配置。对于快速入门例子，我们可以做如下改造
# swagger resource zuul.routes.user.path=/service-a/** zuul.routes.user.url=http://localhost:10010/ # swagger resource zuul.routes.product.path=/service-b/** zuul.routes.product.url=http://localhost:10020/ # use zuul routes generate swagger resources swagger.butler.auto-generate-from-zuul-routes=true
在设置了swagger.butler.auto-generate-from-zuul-routes=true之后会默认的根据zuul中的路由信息来生成SwaggerResource。其中，原来resource中的name会使用zuul route的名称（比如：上面的user和product），而api-docs-path和swagger-version配置会使用默认的全局配置。如果resource中的三个参数有特殊情况要处理，可以采用快速入门中的配置方式来特别指定即可。
忽略某些路由生成
# swagger resource zuul.routes.user.path=/service-a/** zuul.routes.user.url=http://localhost:10010/ # swagger resource zuul.routes.product.path=/service-b/** zuul.routes.product.url=http://localhost:10020/ # use zuul routes generate swagger resources swagger.butler.auto-generate-from-zuul-routes=true swagger.butler.ignore-routes=product
如上示例，通过swagger.butler.ignore-routes参数可以从当前配置的路由信息中排除某些路由内容不生成文档，配置内容为zuul中的路由名称，配置多个的时候使用,分割。
注意：
swagger.butler.ignore-routes和swagger.butler.generate-routes不能同时配置。这两个参数都不配置的时候，默认为zuul中的所有路由生成文档。
指定某些路由生成
# swagger resource zuul.routes.user.path=/service-a/** zuul.routes.user.url=http://localhost:10010/ # swagger resource zuul.routes.product.path=/service-b/** zuul.routes.product.url=http://localhost:10020/ # use zuul routes generate swagger resources swagger.butler.auto-generate-from-zuul-routes=true swagger.butler.generate-routes=product
如上示例，通过swagger.butler.generate-routes参数可以从当前配置的路由信息中指定某些路由内容生成文档，配置内容为zuul中的路由名称，配置多个的时候使用,分割。
注意：
swagger.butler.ignore-routes和swagger.butler.generate-routes不能同时配置。这两个参数都不配置的时候，默认为zuul中的所有路由生成文档。
与服务治理整合
与eureka整合
在整合eureka获取所有该注册中心下的API文档时，只需要在上面工程的基础上增加下面的配置：
第一步：pom.xml中增加eureka依赖，比如：
<dependencies> <dependency> <groupId>com.didispace</groupId> <artifactId>swagger-butler-core</artifactId> <version>1.1.0</version> </dependency> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-eureka</artifactId> <version>1.3.2.RELEASE</version> </dependency> </dependencies>
第二步：应用主类增加@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.auto-generate-from-zuul-routes=true swagger.butler.generate-routes=swagger-service-a, swagger-service-b swagger.butler.resources.swagger-service-b.api-docs-path=/xxx/v2/api-docs
由于整合了eureka之后，zuul会默认为所有注册服务创建路由配置（默认的路由名为服务名），所以只需要通过swagger.butler.auto-generate-from-zuul-routes=true参数开启根据路由信息生成文档配置的功能，配合swagger.butler.ignore-routes和swagger.butler.generate-routes参数就可以指定要生成的范围了，如果某些服务需要特殊配置，也可以通过wagger.butler.resources.*的配置来覆盖默认设置，比如上面的swagger.butler.resources.swagger-service-b.api-docs-path=/xxx/v2/api-docs指定了swagger-service-b服务获取swagger文档的请求路径为/xxx/v2/api-docs。
代码示例具体可见
swagger-butler-example-eureka目录
与consul整合
在整合eureka获取所有该注册中心下的API文档时，只需要在上面工程的基础上增加下面的配置：
第一步：pom.xml中增加consul依赖，比如：
<dependencies> <dependency> <groupId>com.didispace</groupId> <artifactId>swagger-butler-core</artifactId> <version>1.1.0</version> </dependency> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-consul-discovery</artifactId> <version>1.3.2.RELEASE</version> </dependency> </dependencies>
第二步：应用主类增加@EnableDiscoveryClient，比如：
@EnableDiscoveryClient @EnableSwaggerButler @SpringBootApplication public class EurekaApplication { public static void main(String[] args) { SpringApplication.run(EurekaApplication.class); } }
第三步：配置文件中增加eureka的配置，比如
pring.application.name=swagger-butler-example-consul server.port=11002 spring.cloud.consul.host=localhost spring.cloud.consul.port=8500 swagger.butler.auto-generate-from-zuul-routes=true swagger.butler.generate-routes=swagger-service-a, swagger-service-b swagger.butler.resources.swagger-service-b.api-docs-path=/xxx/v2/api-docs
里除了consul自身的配置之外，其他内容与整合eureka时候的是一样的。
代码示例具体可见
swagger-butler-example-consul目录
