- Swagger作为接口文档工具接入springboot工程很方便,只需一个starter,一个configuration就可集成完毕
- 但是对于有较多微服务的系统来说,一个服务一个文档地址,便会觉得比较麻烦。有没有什么好的办法可以都把他们集中起来?
- 这时候聚合文档的解决方案出现了,将所有的微服务地址以swagger分组的形式展现,切换分组的时候就相当于直接切换了整个微服务。
- SpringBlade对聚合文档做了优化,提供了更简单、配置更方便的解决方案,那么下面我们来看看具体如何操作。
配置步骤(SpringBlade项目为例)
- 打开blade-gateway的配置文件bootstrap.yml
- 配置需要出现在网关的服务地址,以及显示的服务名
对应服务工程引入 blade-starter-swagger 依赖即可
文档地址
1.打开聚合文档的地址: http://localhost/doc.html
2.点击左上角的下拉框,我们可以看到已经配置好了3个不同的微服务文档。
多包名扫描
bladex提供了多包扫描的配置,具体如下:
给API润色
1.我们可以看到,演示模块的API都是英文,没有中文描述,看起来会比较吃力,那么我们结合下swagger的注解以及swagger-bootstrap-ui的配置,来完整显示下一个常规的API形态。
2.首先把个性化配置都打开。
3.其次加上请求头的Token值(可以直接从授权模块获取),获取后将Token设置到请求头中
4.接着打开演示模块,以排在第二个的/blade-demo/api/detail
接口为例,我想把他排在第一个,并且以中文形态来描述他的api
5.找到对应API,加上如下配置,@ApiOperation
中的position
就是用来设置排序的,值越小,排序越靠前。
@RestController
@AllArgsConstructor
@RequestMapping("api")
@Api(value = "演示接口", tags = "演示接口")
public class DemoController {
private BlogService service;
/**
* 详情
*/
@GetMapping("/detail")
@ApiOperation(value = "查看详情", notes = "传入主键", position = 1)
public R<Blog> detail(@ApiParam(value = "主键值") @RequestParam Integer id) {
Blog detail = service.getById(id);
return R.data(detail);
}
}
6.重启服务查看聚合文档,可以看到,排序、中文生效,一个常规的API形态诞生了。
7.调用下API,看是否返回成功。
8. 如果有些API我们不想显示在文档上,可以使用@ApiIgnore注解,例如加在BlogClientImpl
上。
@ApiIgnore
@RestController
@AllArgsConstructor
public class BlogClientImpl implements BlogClient {
private BlogService service;
@Override
@GetMapping(API_PREFIX + "/detail")
public R<Blog> detail(Integer id) {
return R.data(service.getById(id));
}
}
9.重启服务,查看文档界面已经没有这个API描述了。
注意点
- swagger默认在生产环境
prod
下关闭无法使用,因为在生产环境暴露接口会非常危险 - 若需要开启,可以到对应文件删掉配置