开源：Swagger Butler 1.1.0发布，利用ZuulRoute信息简化配置内容
Swagger Butler是一個基于Swagger與Zuul構建的API文檔匯集工具。通過構建一個簡單的Spring Boot應用，增加一些配置就能將現有整合了Swagger的Web應用的API文檔都匯總到一起，方便查看與測試。
項目地址
- Github：https://github.com/dyc87112/swagger-butler
- Gitee：https://gitee.com/didispace/swagger-butler
快速入門
該工具的時候非常簡單，先通過下面幾步簡單入門：
第一步：構建一個基礎的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功能
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，比如：
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，比如：
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.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目錄
貢獻者
- 程序猿DD
公眾號
總結
以上是生活随笔為你收集整理的开源：Swagger Butler 1.1.0发布，利用ZuulRoute信息简化配置内容的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 全网Star最多（近20k）的Sprin
- 下一篇： Spring Boot应用的后台运行配置