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的配置，比如：

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時候的是一樣的。

1、具有1-5工作經驗的，面對目前流行的技術不知從何下手，

需要突破技術瓶頸的可以加。

2、在公司待久了，過得很安逸，

但跳槽時面試碰壁。

需要在短時間內進修、跳槽拿高薪的可以加。

3、如果沒有工作經驗，但基礎非常紮實，對java工作機制，

常用設計思想，常用java開發框架掌握熟練的，可以加。

4、覺得自己很牛B，一般需求都能搞定。

但是所學的知識點沒有系統化，很難在技術領域繼續突破的可以加。

5. 群號：高階架構群 Java進階群：180705916.備註好資訊！送架構視訊。

6.阿里Java高階大牛直播講解知識點，分享知識，

多年工作經驗的梳理和總結，帶著大家全面、

科學地建立自己的技術體系和技術認知！