开源:Swagger Butler 1.1.0发布,利用ZuulRoute信息简化配置内容

【推荐阅读】撸了今年阿里、腾讯和美团的面试,我有一个重要发现...
文章目录
  1. 1. 快速入门
  2. 2. Zuul的路由与SwaggerResources配置之间的关系
  3. 3. 全局配置
  4. 4. 使用Zuul中的路由自动配置(新特性)
    1. 4.1. 忽略某些路由生成
    2. 4.2. 指定某些路由生成
  5. 5. 与服务治理整合
    1. 5.1. 与eureka整合
    2. 5.2. 与consul整合
    3. 5.3. 贡献者
    4. 5.4. 公众号

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

Example

代码示例具体可见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-pathswagger-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-pathswagger-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-routesswagger.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-routesswagger.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-routesswagger.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时候的是一样的。

代码示例具体可见swagger-butler-example-consul目录

贡献者

公众号

干货分享