Swagger Butler是一個(gè)基于Swagger與Zuul構(gòu)建的API文檔匯集工具。通過(guò)構(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

快速入門

該工具的時(shí)候非常簡(jiǎn)單，先通過(guò)下面幾步簡(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.1.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 # 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

上面配置了兩個(gè)文檔位置，由于這里還沒有引入服務(wù)發(fā)現(xiàn)機(jī)制，所以Zuul的路由需要我們自己配置。然后在配置resource信息的時(shí)候，從1.1.0版本開始做了較大的調(diào)整，由于具體的訪問路徑是可以通過(guò)路由信息產(chǎn)生的，所以對(duì)于resource的配置信息只關(guān)注三個(gè)內(nèi)容：

• name：API文檔在swagger中展現(xiàn)名稱
• api-docs-path：要獲取的swagger文檔的具體路徑；如果不配置會(huì)使用全局的swagger.butler.api-docs-path配置，默認(rèn)為/v2/api-docs。；這里的配置主要用戶一些特殊情況，比如服務(wù)自身設(shè)置了context-path，或者修改了swagger默認(rèn)的文檔路徑
• swagger-version：swagger版本信息；如果不配置會(huì)使用全局的swagger.butler.swagger-version配置，默認(rèn)為2.0。

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

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

Zuul的路由與SwaggerResources配置之間的關(guān)系

如上示例中<route-name>展示了Zuul的路由名稱與SwaggerResources配置之間的關(guān)聯(lián)關(guān)系

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

注意：在沒有使用自動(dòng)配置或整合服務(wù)治理的時(shí)候，要生成Swagger文檔的時(shí)候，resources信息中的name屬性是必須配置的，api-docs-path和swagger-version不配置的時(shí)候會(huì)使用默認(rèn)的全局配置

全局配置

對(duì)于Swagger文檔獲取的全局配置內(nèi)容，目前主要包含下面幾個(gè)參數(shù)：

swagger.butler.api-docs-path=/v2/api-docs swagger.butler.swagger-version=2.0

使用Zuul中的路由自動(dòng)配置（新特性）

在快速入門示例中我們配置了兩個(gè)路由信息，同時(shí)為這兩個(gè)路由信息配置了對(duì)應(yīng)的Swagger信息來(lái)獲取API文檔詳情，從1.1.0版本開始，增加了幾個(gè)通過(guò)Zuul的路由配置來(lái)自動(dòng)生成文檔信息的參數(shù)，這樣可以減少快速入門示例中那些繁瑣的配置。對(duì)于快速入門例子，我們可以做如下改造：

# 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

在設(shè)置了swagger.butler.auto-generate-from-zuul-routes=true之后會(huì)默認(rèn)的根據(jù)zuul中的路由信息來(lái)生成SwaggerResource。其中，原來(lái)resource中的name會(huì)使用zuul route的名稱（比如：上面的user和product），而api-docs-path和swagger-version配置會(huì)使用默認(rèn)的全局配置。如果resource中的三個(gè)參數(shù)有特殊情況要處理，可以采用快速入門中的配置方式來(lái)特別指定即可。

忽略某些路由生成

# 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

如上示例，通過(guò)swagger.butler.ignore-routes參數(shù)可以從當(dāng)前配置的路由信息中排除某些路由內(nèi)容不生成文檔，配置內(nèi)容為zuul中的路由名稱，配置多個(gè)的時(shí)候使用,分割。

注意：swagger.butler.ignore-routes和swagger.butler.generate-routes不能同時(shí)配置。這兩個(gè)參數(shù)都不配置的時(shí)候，默認(rèn)為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

如上示例，通過(guò)swagger.butler.generate-routes參數(shù)可以從當(dāng)前配置的路由信息中指定某些路由內(nèi)容生成文檔，配置內(nèi)容為zuul中的路由名稱，配置多個(gè)的時(shí)候使用,分割。

注意：swagger.butler.ignore-routes和swagger.butler.generate-routes不能同時(shí)配置。這兩個(gè)參數(shù)都不配置的時(shí)候，默認(rèn)為zuul中的所有路由生成文檔。

與服務(wù)治理整合

與eureka整合

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

第一步：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>

第二步：應(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.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會(huì)默認(rèn)為所有注冊(cè)服務(wù)創(chuàng)建路由配置（默認(rèn)的路由名為服務(wù)名），所以只需要通過(guò)swagger.butler.auto-generate-from-zuul-routes=true參數(shù)開啟根據(jù)路由信息生成文檔配置的功能，配合swagger.butler.ignore-routes和swagger.butler.generate-routes參數(shù)就可以指定要生成的范圍了，如果某些服務(wù)需要特殊配置，也可以通過(guò)wagger.butler.resources.*的配置來(lái)覆蓋默認(rèn)設(shè)置，比如上面的swagger.butler.resources.swagger-service-b.api-docs-path=/xxx/v2/api-docs指定了swagger-service-b服務(wù)獲取swagger文檔的請(qǐng)求路徑為/xxx/v2/api-docs。

代碼示例具體可見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.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>

第二步：應(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.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自身的配置之外，其他內(nèi)容與整合eureka時(shí)候的是一樣的。

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

貢獻(xiàn)者

• 程序猿DD

公眾號(hào)

---

總結(jié)

以上是生活随笔為你收集整理的开源：Swagger Butler 1.1.0发布，利用ZuulRoute信息简化配置内容的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。