微服务项目Swagger聚合文档的用法，将所有的微服务地址以Swagger分组的形式展现

  

• 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下关闭无法使用，因为在生产环境暴露接口会非常危险
• 若需要开启，可以到对应文件删掉配置