## 前言 * Swagger作为接口文档工具接入springboot工程很方便,只需一个starter,一个configuration就可集成完毕 * 但是对于有较多微服务的系统来说,一个服务一个文档地址,便会觉得比较麻烦。有没有什么好的办法可以都把他们集中起来? * 这时候聚合文档的解决方案出现了,将所有的微服务地址以swagger分组的形式展现,切换分组的时候就相当于直接切换了整个微服务。 * BladeX对聚合文档做了优化,提供了更简单、配置更方便的解决方案,那么下面我们来看看具体如何操作。 ## 如何配置 * 打开`blade-swagger`工程的配置文件`application.yml` * 配置需要出现在网关的服务地址,以及显示的服务名,其中`uri`为网关地址,`location`是对应服务名的swagger-api地址 ![](https://img.kancloud.cn/db/80/db805ff5fcdfa46c892da4a92f64bd2a_1488x1446.png) * 对应服务工程引入 blade-core-boot 依赖即可,此依赖会自动加载swagger所需的依赖 ![](https://img.kancloud.cn/b4/c0/b4c029b4b40882825dd7874b8200612c_1978x1534.png) ## 文档地址 1. 我们不妨先打开下聚合文档的地址,开启所有增强配置: http://localhost:18000/doc.html **注⚠️:** - **新版本开始把swagger网关单独抽离到了`blade-swagger`服务,请单独启动并访问** - **虽然swagger服务已经独立,但仍然需要开启网关进行服务转发才可以正常访问** ![](https://img.kancloud.cn/13/7c/137c6af613054f0101dd97c20a1926ab_2566x1238.png) 2. 点击左上角的下拉框,我们可以看到已经配置好了3个不同的微服务文档。 ![](https://img.kancloud.cn/00/ca/00cae1cb18a1aee9a568337d4874de3d_2484x1426.png) ## API润色 1. swagger增强插件knife4j有不少好用的功能,我们下面来简单介绍一下,当然详细说明请查阅官方文档:https://doc.xiaominfo.com/docs/features/enhance 2. 首先把个性化配置都打开,**目前knife4j版本刷新后会丢失增强配置,所以需要手动关闭tab,再重新打开文档页面才会生效**。 ![](https://img.kancloud.cn/8e/ca/8ecaf1907d6c0ef3dae203ee03d259ad_2180x1112.png) 3. 其次加上请求头的Token值(可以直接从授权模块获取),获取后将Token设置到请求头中 ![](https://img.kancloud.cn/93/97/93979dd780f7e6c0b75b1e372728df44_2632x1474.png) 4. 接着我们在`blade-swagger`的配置文件加上演示模块并启动服务 ![](https://img.kancloud.cn/36/42/364204a92ee341e97fa17eb45002cb19_1638x970.png) ![](https://img.kancloud.cn/e3/95/e3952e3dd9bf37f49a22d606b88acf8c_2554x1860.png) ![](https://img.kancloud.cn/2a/fe/2afe37edec25aef34cb9e5814b31e042_3206x920.png) 5. 重启blade-swagger服务后,刷新首页,就可以在左上角便可以看到对应选项了 ![](https://img.kancloud.cn/a0/2d/a02d278013364fe93506926eb3c005fa_1942x1244.png) 6. 若大家想实时修改聚合文档的信息,可以把`blade-swagger`的聚合文档配置删掉,然后到nacos进行新增即可 7. 接着打开演示模块,以排在第二个的`/blade-demo/getNameByProps`接口为例,我想把他排在第一个,并且以中文形态来描述他的api ![](https://img.kancloud.cn/62/cd/62cd16931c5d763997d5001dd9c7f122_632x1036.png) 8. 找到对应API,加上如下配置,`@ApiOperationSupport`中的`order`就是用来设置排序的,值越小,排序越靠前。 ![](https://img.kancloud.cn/4c/d4/4cd459a9a95e59fabed0b050998b03fd_2476x1564.png) ~~~java @GetMapping("name-by-props") @ApiOperation(value = "查看名称", notes = "排序测试") @ApiOperationSupport(order = 1) public String getNameByProps() { return properties.getName(); } ~~~ 6. 重启服务查看聚合文档,可以看到,排序、中文生效,一个常规的API形态诞生了。 ![](https://img.kancloud.cn/c1/95/c19552156927f18fe8131e0b13c96adc_1750x1122.png) 7. 调用下API,返回成功,后续编写文档就可以放心的交给对接的团队啦! ![](https://img.kancloud.cn/b7/d1/b7d14d6683a4422cdff9291e65ea0aee_2306x1100.png) 8. 如果有些API我们不想显示在文档上,可以使用@ApiIgnore注解,例如我们加在刚刚的方法上 ~~~java @ApiIgnore @GetMapping("name-by-props") @ApiOperation(value = "查看名称", notes = "排序测试") @ApiOperationSupport(order = 1) public String getNameByProps() { return properties.getName(); } ~~~ 9. 重启服务,查看文档界面已经没有这个API描述了。 ![](https://img.kancloud.cn/ab/1f/ab1f0a78a1f9ece3b28a3b4a881877e4_1266x974.png) ## 注意点 * swagger默认在生产环境`prod`下关闭无法使用,因为在生产环境暴露接口会非常危险 * 若需要开启,请使用`test`环境启动测试 ## 结束语 本文讲述了聚合文档的实现以及Swagger接口描述的润色,想知道更多用法,还需查看官方文档。 * swagger文档直达:https://swagger.io/ * swagger-bootstrap-ui文档直达:https://doc.xiaominfo.com/docs/quick-start