一、SpringCloud+Gateway+Swagger2

做个笔记，并分享（）。。。

学习链接：

Spring Cloud Gateway系列【13】 整合knife4j实现网关聚合接口文档_knife4j-gateway-spring-boot-starter-CSDN博客

1、需求：

实现knife4j样式的接口文档；各个模块都加载到gateway;

效果图：

2、准备工作

第一步：搭建SpringCloud框架（不具体写步骤了）

第二步：新建一个Gateway模块，命名cloud-api-gateway

（如果添加了过滤器、security，可能需要检查是否会拦截，可能需要在拦截的地方将 "/v2/api-docs"、样式等放行。。。）

引入依赖

<!--gateway-->
<dependency>
   <groupId>org.springframework.cloud</groupId>
   <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>

yml配置文件中添加（具体操作和作用自行搜索）

    gateway:
      discovery:
        locator:
          enabled: true  #表明gateway开启服务注册和发现的功能，并且spring cloud gateway自动根据服务发现为每一个服务创建了一个router，这个router将以服务名开头的请求路径转发到对应的服务
          lower-case-service-id: true  #是将请求路径上的服务名配置为小写（因为服务注册的时候，向注册中心注册时将服务名转成大写的了
#      routes:
#        -id: mcroservice-payment  #自定义id,无意义但不能重复，最好跟服务名保持一致
#        uri: lb://mcroservice-payment  # 注册中心中的服务器名称
#        predicates:
#          - Path=/payment/** # 转发该路径
#        filters:
#          - StripPrefix=1 #必须加上StripPrefix=1，否则访问服务时会带上user
      # 经过gateWay网关时，需要在网关统一配置跨域请求，全部通过
      globalcors:
        cors-configurations:
          '[/**]':
            allowed-origins: "*"
            allowed-headers: "*"
            allow-credentials: true
            allowed-methods:
              - GET
              - POST
              - DELETE
              - PUT
              - OPTION

第三步：新建swagger模块，用于设置展示的样式，我是新建了一个common子模块，再在子模块下新建了cloud-common-swagger（方便统一管理工具类）

引入依赖

<dependencies>
    <!--knife4j文档，其实包含springfox依赖-->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <version>2.0.9</version>
    </dependency>

  	<!-- swagger2-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
</dependencies>

项目结构图：

3、操作步骤

3.1、cloud-common-swagger模块

3.1.1 新建config文件夹并创建类SwaggerConfiguration

@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfiguration {

    @Bean(value = "userApi")
    @Order(value = 1)
    public Docket groupRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(groupApiInfo())
                .select()
                // 加载所有包含Api的             
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(this.getParameterList());// 全局配置
    }

    private ApiInfo groupApiInfo() {
        return new ApiInfoBuilder()
                .title("swagger")
                .description("<div style='font-size:14px;color:red;'>swagger-bootstrap-ui-demo RESTful APIs</div>")
                .termsOfServiceUrl("http://www.group.com/")
                .contact("group@qq.com")
                .version("1.0")
                .build();
    }

    /**
     * 添加head参数配置
     * @return
     */
    private List<Parameter> getParameterList() {
        ParameterBuilder clientIdTicket = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        clientIdTicket.name("token").description("token令牌") //自定义名称
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false).build(); //设置false，表示clientId参数 非必填,可传可不传！
        pars.add(clientIdTicket.build());
        return pars;
    }
}

3.2、cloud-api-gateway模块

如果是单体项目，前面已经可以实现了。多服务项目需要统一管理，现在是为了聚合所有服务的接口。

3.2.1 引入swagger的依赖

<!-- swagger2依赖 （网关不写业务，但是需要聚合所有服务的接口方便查看）-->
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-spring-boot-starter</artifactId>
	<version>2.0.9</version>
</dependency>

3.2.2 新建swagger文件夹（每个功能点新建一个文件夹方便查看维护）

 页面其实是通过/swagger-resources 路径来访问展示资源的，那么我们可以重写这个接口。将资源加载到下边。

@Component
@RequiredArgsConstructor
public class MySwaggerResourceProvider implements SwaggerResourcesProvider {

    /**
     * swagger2默认的url后缀
     */
    private static final String SWAGGER2_URL = "/v2/api-docs";

    /**
     * 路由定位器
     */
    private final RouteLocator routeLocator;

    /**
     * 网关应用名称
     */
    @Value("${spring.application.name}")
    private String gatewayName;

    /**
     * 获取 Swagger 资源
     */
    @Override
    public List<SwaggerResource> get() {
        List<SwaggerResource> resources = new ArrayList<>();
        List<String> routeHosts = new ArrayList<>();
        // 1. 获取路由Uri 中的Host=> 服务注册则为服务名=》app-service001
        routeLocator.getRoutes()
                .filter(route -> route.getUri().getHost() != null)
                .filter(route -> !gatewayName.equals(route.getUri().getHost()))
                .subscribe(route -> routeHosts.add(route.getUri().getHost()));
        // 2. 创建自定义资源
        for (String routeHost : routeHosts) {
            String serviceUrl = "/" + routeHost + SWAGGER2_URL; // 后台访问添加服务名前缀
            SwaggerResource swaggerResource = new SwaggerResource(); // 创建Swagger 资源
            swaggerResource.setUrl(serviceUrl); // 设置访问地址
            swaggerResource.setName(routeHost); // 设置名称
            swaggerResource.setSwaggerVersion("3.0.0");
            resources.add(swaggerResource);
        }
        return resources;
    }
}

@RestController
@RequestMapping("/swagger-resources")
@RequiredArgsConstructor
public class SwaggerResourceController {


    private final MySwaggerResourceProvider swaggerResourceProvider;

    @RequestMapping
    public ResponseEntity<List<SwaggerResource>> swaggerResources() {
        return new ResponseEntity<>(swaggerResourceProvider.get(), HttpStatus.OK);
    }
}

4、演示结果

访问地址：http://ip:port/doc.html#/home

子模块中引入cloud-common-swagger模块，因为我们要统一版本管理，需要swagger文档的就引入

在启动类中加入注解  @EnableSwagger2

在Controller方法上加上对应的swagger注解

启动模块后再启动gateway模块就可以了