Spring Cloud程序快速接入SpringFox-swagger2

1. pom.xml中添加依赖

<!-- swagger --> 
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-bean-validators</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

2. 和Application配置启动类同级添加Swagger配置类 参考代码

   需要根据实际情况修改的代码:

   .apis(RequestHandlerSelectors.basePackage("com.demo.controller"))// 扫描该包下的所有需要在Swagger中展示的API，@ApiIgnore注解标注的除外

3. 文档注解使用参考

   注解使用参考

4. 关于swaggerui-eureka

   默认情况下,每个微服务暴露的端口下

   会对外提供api访问(http:${host}:${port}/swagger-ui.html);
   会对外提供json格式的openapi spec访问地址(http:${host}:${port}/v2/api-docs).

   这种情况在服务众多的情况下就是个灾难........,虽然swagger-ui可以通过查询openapi spec地址的方式进行显示,但是如果将spec导出那么代码和api又分离了,有违初衷.

   虽然swagger提供了以添加SwaggerResource的方式,在界面上方显示所有服务的spec,但是在使用swagger进行接口测试时,相同的服务将会合并,无法做到针对指定部署到服务的机器发起请求.并且管理所有服务的路由也要耦合到业务网关中.并且最新的springfox-swagger-ui 2.8.0 Release版本发布之后才修复了#issues2235多个api文档在不同ip的机器上无法正确路由的问题.遗憾的是时隔3个月了(本文编写时),仍然没有发布小的release版本.

   基于以上考虑,所以开发了swaggerui-eureka,因为所有微服务都是注册在 eureka上面,且api的地址是有规律可循的,即获取微服务实例uri+/swagger-ui.html]即可获取实时的所有在开发/测试环境的api. 如图:(承认较丑,前端有几年没写了,有时间则修好看点....)

   

   a) 针对以上问题,在swagger2.8.0之后的版本发布之前,修改本地maven仓库中的jar包.
   springfox-swagger-ui-2.8.0.jar\META-INF\resources\webjars\springfox-swagger-ui\springfox.js

   resources.forEach(resource => {
   resource.url = baseUrl + resource.url;
   });

   修改为

   resources.forEach(resource => {
   if (resource.url.substring(0, 4) !== 'http') {
   resource.url = baseUrl + resource.url;
   }
   });

   b) 实际上api非常多之后,swaggerui自带的下拉列表并不好用,也不能检索.后续可以再swaggerui-eureka上方加入快捷搜索栏.