β

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

程序猿DD | 博客 13 阅读

Swagger Butler是一个基于Swagger与Zuul构建的API文档汇集工具。通过构建一个简单的Spring Boot应用,增加一些配置就能将现有整合了Swagger的Web应用的API文档都汇总到一起,方便查看与测试。

项目地址

快速入门

该工具的时候非常简单,先通过下面几步简单入门:

第一步 :构建一个基础的Spring Boot应用

如您还不知道如何创建Spring Boot应用,可以先阅读 本篇入门文章

第二步 :在pom.xml中引入依赖

@EnableSwaggerButler
@SpringBootApplication
public class StaticApplication {

public static void main(String[] args) {
SpringApplication.run(StaticApplication.class);
}

}

第四步 :配置文件中增加Swagger文档的地址配置

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 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.generate-routes=product

如上示例,通过 swagger.butler.generate-routes 参数可以从当前配置的路由信息中指定某些路由内容生成文档,配置内容为zuul中的路由名称,配置多个的时候使用 , 分割。

注意: swagger.butler.ignore-routes swagger.butler.generate-routes 不能同时配置。这两个参数都不配置的时候,默认为zuul中的所有路由生成文档。

与服务治理整合

与eureka整合

在整合eureka获取所有该注册中心下的API文档时,只需要在上面工程的基础上增加下面的配置:

第一步 pom.xml 中增加 eureka 依赖,比如:

@EnableDiscoveryClient
@EnableSwaggerButler
@SpringBootApplication
public class EurekaApplication {

public static void main(String[] args) {
SpringApplication.run(EurekaApplication.class);
}

}

第三步 :修改配置文件,增加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-consul-discovery</artifactId>
<version>1.3.2.RELEASE</version>
</dependency>
</dependencies>

第二步 :应用主类增加 @EnableDiscoveryClient ,比如:

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 目录

贡献者

公众号

干货分享

Swagger Butler是一个基于Swagger与Zuul构建的API文档汇集工具。通过构建一个简单的Spring Boot应用,增加一些配置就能将现有整合了Swagger的Web应用的API文档都汇总到一起,方便查看与测试。

项目地址

作者:程序猿DD | 博客
Dream big, work smart, deliver fast

发表评论