dyc87112 / swagger-butler

API文档管家 - 基于Swagger与Zuul实现的API文档聚合工具

Swagger Butler

当我们构建分布式系统的时候，虽然我们可以用Swagger来方便为每个服务自动产出API文档页面。但是随着服务数量的增多，内部服务间的依赖关系的复杂度增加，每个服务开发人员要关心和查阅的文档变得越来越多。由于每个服务的文档地址可能都不一样，这使得不得不维护一个文档的索引来方便查阅，并且这个索引还需要不断的去维护更新。

那么有没有什么工具可以帮我们快速的汇集这些服务的Swagger文档呢？只需要记住一个访问地址，就可以访问所有服务的API文档？当服务增加的时候，不需要手工维护就能自动发现新服务的API文档？如果您有上面的这些问题，那么不妨看看这个项目，或许可以解决您的这些烦恼！

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

项目地址

• Github：https://github.com/dyc87112/swagger-butler
• Gitee：https://gitee.com/didispace/swagger-butler

使用手册

版本说明

swagger-butler的使用版本与Spring Boot版本直接相关，对应关系如下；

Spring Boot版本	swagger-butler版本
1.x	1.x
2.x	2.x

当前最新版本2.0.0，1.x版本将不再继续更新。

快速入门

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

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

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

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

<dependencies>
    <dependency>
        <groupId>com.didispace</groupId>
        <artifactId>swagger-butler-core</artifactId>
        <version>2.0.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

增强文档：访问http://localhost:11000/doc.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>2.0.0</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-eureka</artifactId>
        <version>2.0.0.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>2.0.0</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-consul-discovery</artifactId>
        <version>2.0.0.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目录

贡献者

• 程序猿DD

推荐内容

• 我的博客
• 知识星球
• Spring Boot基础教程
• Spring Cloud基础教程
• 公益调试Eureka

公众号

swagger-butler's Issues

生产中用你这个插件怎么把swagger屏蔽掉

比如，在测试和开发环境的时候可以让开发看到文档，但是上生产了，这些文档就不允许看到了。能否在网关中有地方快捷配置？

这个插件和swagger-spring-boot-starter插件的区别是？

如题 呵呵

能否整合spring cloud gateway+nacos?

能否支持spring cloud gateway+nacos方案的文档聚合？

兼容k8s

请问这个可以兼容k8s中service的服务发现吗? 我自己测试可以发现k8s中的service, 但是zuul路由失败....
DynamicServerListLoadBalancer for client iov-sjjh-servicenode-channel initialized: DynamicServerListLoadBalancer:{NFLoadBalancer:name=iov-sjjh-servicenode-channel,current list of Servers=[],Load balancer stats=Zone stats: {},Server stats: []}ServerList:com.netflix.loadbalancer.ConfigurationBasedServerList@2a4dda73
2019-04-26 16:27:42.886 WARN 1 --- [nio-8080-exec-2] o.s.c.n.z.filters.post.SendErrorFilter : Error during filtering

兼容boot2.1.x

什么时候兼容2.1.x呢

在配置了Zuul路由之后，可以在路由信息中获取path来设置SwaggerResource

zuul获取不到api的json文件？

1. 首先微服务是可以直接端口访问的
   

2.使用路由访问就不能获取JSON，不知是您的插件问题还是我的配置文件

3. 我的路由配置
   

4. 我的swagger开启

5. swagger配置
   

问题就是第2部里获取不到JSON?

网关调用带有 context-path 的服务 404

1 当 通过 SwaggerButler 聚合网关之后
2 在网关的swagger-ui
3 通过 zuul 调用带有 context-path 的服务的接口
4 发现 404

如果你打印了 请求路由，你会发现缺少了 context-path

附上本人的解决方案 https://blog.csdn.net/qq_35704236/article/details/103636573

调试页面调用的地址是使用swagger-butler所在项目部署的服务器地址 无法请求到配置文件中对应的接口文档地址

swagger-api路径问题

你好，我使用你的代码没什么问题。但是有个问题想向您请假下。

根据我对您代码的理解，聚合的时候，是在返回SwaggerResources集合时，设置了每一个微服务的api-docs地址，且获取所有路由之后再直接替换（如：替换后是 /service-a/v2/api-docs），这样再通过网关请求的时候，会路由到每一个微服务对应的api-docs接口地址，但是每一个api-docs内部的接口地址怎么加上路由地址的前缀呢（如：/service-a），这样才能从网关路由到对应的微服务。

我使用你的代码，看到swagger-ui界面请求的时候是自动加上路由前缀了的，是在源码哪里去做的这个操作呢？这种操作应该跟网关无关吧，我是用的spring-cloud-gateway。

期待您的解答，谢谢！