开源:Swagger Butler 1.1.0发布,利用ZuulRoute信息简化配置内容
Swagger Butler是一个基于Swagger与Zuul构建的API文档汇集工具。通过构建一个简单的Spring Boot应用,增加一些配置就能将现有整合了Swagger的Web应用的API文档都汇总到一起,方便查看与测试。
项目地址
- Github:https://github.com/dyc87112/swagger-butler
- Gitee:https://gitee.com/didispace/swagger-butler
快速入门
该工具的时候非常简单,先通过下面几步简单入门:
第一步:构建一个基础的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@SpringBootApplicationpublic class StaticApplication { public static void main(String[] args) { SpringApplication.run(StaticApplication.class); } } |
第四步:配置文件中增加Swagger文档的地址配置
spring.application.name=swagger-butler-example-staticserver.port=11000 # default configswagger.butler.api-docs-path=/v2/api-docsswagger.butler.swagger-version=2.0 # swagger resourcezuul.routes.user.path=/service-a/**zuul.routes.user.url=http://localhost:10010/swagger.butler.resources.user.name=user-service # swagger resourcezuul.routes.product.path=/service-b/**zuul.routes.product.url=http://localhost:10020/swagger.butler.resources.product.name=product-serviceswagger.butler.resources.product.api-docs-path=/xxx/v2/api-docsswagger.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-serviceswagger.butler.resources.<route-name>.api-docs-path=/xxx/v2/api-docsswagger.butler.resources.<route-name>.swagger-version=2.0 |
注意:在没有使用自动配置或整合服务治理的时候,要生成Swagger文档的时候,resources信息中的
name
属性是必须配置的,api-docs-path
和swagger-version
不配置的时候会使用默认的全局配置
全局配置
对于Swagger文档获取的全局配置内容,目前主要包含下面几个参数:
swagger.butler.api-docs-path=/v2/api-docsswagger.butler.swagger-version=2.0 |
使用Zuul中的路由自动配置(新特性)
在快速入门示例中我们配置了两个路由信息,同时为这两个路由信息配置了对应的Swagger信息来获取API文档详情,从1.1.0版本开始,增加了几个通过Zuul的路由配置来自动生成文档信息的参数,这样可以减少快速入门示例中那些繁琐的配置。对于快速入门例子,我们可以做如下改造:
# swagger resourcezuul.routes.user.path=/service-a/**zuul.routes.user.url=http://localhost:10010/ # swagger resourcezuul.routes.product.path=/service-b/**zuul.routes.product.url=http://localhost:10020/ # use zuul routes generate swagger resourcesswagger.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 resourcezuul.routes.user.path=/service-a/**zuul.routes.user.url=http://localhost:10010/ # swagger resourcezuul.routes.product.path=/service-b/**zuul.routes.product.url=http://localhost:10020/ # use zuul routes generate swagger resourcesswagger.butler.auto-generate-from-zuul-routes=trueswagger.butler.ignore-routes=product |
如上示例,通过swagger.butler.ignore-routes
参数可以从当前配置的路由信息中排除某些路由内容不生成文档,配置内容为zuul中的路由名称,配置多个的时候使用,
分割。
注意:
swagger.butler.ignore-routes
和swagger.butler.generate-routes
不能同时配置。这两个参数都不配置的时候,默认为zuul中的所有路由生成文档。
指定某些路由生成
# swagger resourcezuul.routes.user.path=/service-a/**zuul.routes.user.url=http://localhost:10010/ # swagger resourcezuul.routes.product.path=/service-b/**zuul.routes.product.url=http://localhost:10020/ # use zuul routes generate swagger resourcesswagger.butler.auto-generate-from-zuul-routes=trueswagger.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@SpringBootApplicationpublic class EurekaApplication { public static void main(String[] args) { SpringApplication.run(EurekaApplication.class); } } |
第三步:修改配置文件,增加eureka的配置,比如:
spring.application.name=swagger-butler-example-eurekaserver.port=11001 eureka.client.service-url.defaultZone=http://eureka.didispace.com/eureka/ swagger.butler.auto-generate-from-zuul-routes=trueswagger.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@SpringBootApplicationpublic class EurekaApplication { public static void main(String[] args) { SpringApplication.run(EurekaApplication.class); } } |
第三步:配置文件中增加eureka的配置,比如:
spring.application.name=swagger-butler-example-consulserver.port=11002 spring.cloud.consul.host=localhostspring.cloud.consul.port=8500 swagger.butler.auto-generate-from-zuul-routes=trueswagger.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
公众号
开源:Swagger Butler 1.1.0发布,利用ZuulRoute信息简化配置内容相关推荐
- 最适合中国国情的开源授权协议ZPL 1.0发布
为什么80%的码农都做不了架构师?>>> 最适合中国国情的开源授权协议: Z PUBLIC LICENSE 1.0 发布了.欢迎大家访问:http://zpl.pub 一.英文 ...
- Wizard 开源文档管理系统1.0发布啦
Wizard 是一款开源文档管理系统,项目地址为 https://github.com/mylxsw/wizard.这个项目是 我 在2017年就开始开发的,起初只是想做一款能够在公司内部把Swagg ...
- Java开源开发平台O2OA V7.0发布,支持Docker容器化部署和三员管理模式
O2OA开发平台开源至今,已经有很多开发者参与我们每个版本的迭代和更新,有的开发者已经利用O2OA在公司内部搭建公司的开发平台,有的开发者在商业项目中使用O2OA平台作为信息化系统建设的基础能力平台. ...
- 完全开源im框架_【行业资讯】移动端开源 IM 框架 MobileIMSDK v5.0 发布!
一.更新内容简介 本次更新为主要版本更新,强势升级,可同时支持TCP.UDP两种协议,精心封装之下,实现一套API.两种协议同时并存.可能是市面上唯一同时支持UDP+TCP两种协议的同类IM框架. 二 ...
- HTML5开源游戏引擎lufylegend1.7.0发布
lufylegend1.7.0版发布,下载包内含开发示例已经增加到20多个,为了更方便操作游戏中的声音等,加入了音频和视频操作,另外更新了API文档. lufylegend.js引擎的下载链接 htt ...
- C#开源音乐播放器MetroPlayer3.0发布
一.说明 MetroPlayer3.0是在MetroMusic1.05及2.0版本的基础之上,进行重构和改进的软件产品.从3.0开始,本软件正式更名为MetroPlayer.MetroPlayer ...
- 开源进展 | WeCross v1.2.0 发布,实现FISCO BCOS与Fabric 2.0 的跨链适配
WeCross是微众银行自主研发并完全开源的区块链跨链协作平台,致力于促进跨行业.机构和地域的跨区块链信任传递和商业合作,有助于实现异构区块链系统之间安全可信的互操作. WeCross v1.0.0. ...
- HTML5开源游戏引擎lufylegend1.5.0发布
说明 lufylegend1.5.0版终于发布了,本来打算再完善一下才发布的,但是最近实在太忙了,1.5.0版拖了又拖,所以决定先发布,等继续完善后再发布1.5.1版,API也相对完善了一下,并加入到 ...
- AgileConfig-轻量级配置中心 1.1.0 发布,支持应用间配置继承
AgileConfig轻量级配置中心自第一个版本发布不知不觉已经半年了.在并未进行什么推广的情况下收到了250个star,对我有很大的鼓舞,并且也有不少同学试用,并且给出了宝贵的意见,非常感谢他们.其 ...
最新文章
- ADPRL - 近似动态规划和强化学习 - Note 10 - 蒙特卡洛法和时序差分学习及其实例 (Monte Carlo and Temporal Difference)
- Web性能压力测试工具——Siege详解
- 用了这么多年 curl,竟然不知道还有这种用法?!
- java的构造特点_JAVA学习第八课(构造函数及其特点)
- C语言 二维数组行数和列数计算 - C语言零基础入门教程
- PowerPivot for Sharepoint 2010 配制及常见错误
- mysql基础,索引
- ImportError: dlopen: cannot load any more object with static TLS 解决
- CentOS 7下网络设备命名
- delaunay三角网构建
- mysql关联力控_力控软件和三菱PLC的通讯模块通讯设定
- 记账系统推荐金蝶精斗云_金蝶精斗云是免费会计记账软件吗?
- [架构之美]一款APP从想法-开发-上线-产品的全过程
- origin画图对图片进行缩放时,如何不让文字一同缩放?
- Flutter web 滚动循环 title(Flutter Web端 滚动显示浏览器标签页名)
- SpringBoot-日志配置
- Arduino 实验 —— 红外遥控RGB灯
- 1. Resnet网络详解
- 音视频之渲染yuv图片
- c51语言语句 指令集,关于 NOP 指令 汇编
热门文章
- 12 哈希表相关类——Live555源码阅读(一)基本组件类
- 对一个 复杂的json结果进行取值的例子
- 通过SQL Server 2008 访问Oracle 10g
- Exchange2003启用web页面登陆(表单型身份验证)
- centos 开发环境配置
- Be My Eyes app:我是你的眼
- 一个单向链表,输出该链表中倒数第k个结点,链表的倒数第0个结点为链表的尾指针
- ioremap,你应该知道的事
- 一道90%都会做错的指针题
- mysql inner join where_详解mysql 使用left join添加where条件的问题分析