springcloud gateway整合swagger做分布式聚合文档

项目中使用gateway做路由，根据请求头访问不同的api，api中使用openfegin，去访问对应的service。为了说明配置，摘取项目核心的代码。包括gateway,user-api,standard-api。

1.swagger依赖

gateway和api中的需要引入swagger的相应依赖：

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

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
</dependencies>      

2.gateway中配置加载swagger信息

import com.ruizhi.detection.component.SwaggerProvider;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.swagger.web.*;

import java.util.List;

/**
 * @description: 用于加载swagger中相关信息的controller
 * @Author: 
 * @Date: 2020/2/11 11:27
 */
@RestController
@RequestMapping("/swagger-resources")
public class SwaggerResourceController {

    private SwaggerProvider swaggerProvider;

    // TODO: 添加权限校验
    @Autowired
    public SwaggerResourceController(SwaggerProvider swaggerProvider) {
        this.swaggerProvider = swaggerProvider;
    }

    @RequestMapping(value = "/configuration/security")
    public ResponseEntity<SecurityConfiguration> securityConfiguration() {
        return new ResponseEntity<>(SecurityConfigurationBuilder.builder().build(), HttpStatus.OK);
    }

    @RequestMapping(value = "/configuration/ui")
    public ResponseEntity<UiConfiguration> uiConfiguration() {
        return new ResponseEntity<>(UiConfigurationBuilder.builder().build(), HttpStatus.OK);
    }

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

3.gateway中配置nacos中注册的服务

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.stereotype.Component;
import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;

/**
 * @description: 用于加载在nacos中注册的服务
 * @Author:
 * @Date: 2020/2/11 11:23
 */
@Component
public class SwaggerProvider implements SwaggerResourcesProvider {

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

    /**
     * 网关路由
     */
    private final RouteLocator routeLocator;

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

    @Autowired
    public SwaggerProvider(RouteLocator routeLocator) {
        this.routeLocator = routeLocator;
    }

    @Override
    public List<SwaggerResource> get() {
        List<SwaggerResource> resources = new ArrayList<>();
        List<String> routeHosts = new ArrayList<>();
        // 获取所有可用的host：serviceId
        routeLocator.getRoutes().filter(route -> route.getUri().getHost() != null)
                .filter(route -> !self.equals(route.getUri().getHost()))
                .subscribe(route -> routeHosts.add(route.getUri().getHost()));
        // 记录已经添加过的server，存在同一个应用注册了多个服务在nacos上
        Set<String> dealed = new HashSet<>();
        routeHosts.forEach(instance -> {
            // 拼接url
            String url = "/" + instance + SWAGGER2URL;
            if (!dealed.contains(url)) {
                dealed.add(url);
                SwaggerResource swaggerResource = new SwaggerResource();
                swaggerResource.setUrl(url);
                swaggerResource.setName(instance);
                resources.add(swaggerResource);
            }
        });
        return resources;
    }
}

4.user-api和standard-api中设置swagger中的配置

这两个类基本上差不多，我只贴其中一个

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @description: 配置描述swagger的描述
 * @Author: 
 * @Date: 2020/2/11 11:47
 */
@EnableSwagger2
@Configuration
public class SwaggerConfig {

    /**
     * 创建API
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 详细定制
                .apiInfo(apiInfo("1.0.0"))
                .select()
                // 指定扫描的包路径
              .apis(RequestHandlerSelectors.basePackage("com.detection.controller"))
                // 扫描所有
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo(String version) {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                .title("标准管理的接口文档")
                .version(version)
                .build();
    }
}

5.gateway中路由规则的配置

spring:
  cloud:
    gateway:
      enabled: true
      discovery:
        locator:
          lower-case-service-id: true
      routes:
        #netty 路由过滤器(数组)，http或https开头 lb://代表是服务的名称  predicates:表示会过滤掉的请求头
        - id: user-router
          uri: lb://user-api
          predicates:
            - Path=/user-api/**
          filters:
          - StripPrefix=1
        - id: standard-router
          uri: lb://standard-api
          predicates:
            - Path=/standard-api/**
          filters:
          - StripPrefix=1
        - id: file-upload-router
          uri: lb://file-service
          predicates:
            - Path=/file-service/**
          filters:
          - StripPrefix=1
    #处理跨域请求问题
    globalcors:
      cors-configurations:
        '[/**]':
          allowedOrigins: "*"
          allowedMethods: "*"

这里需要主要path中的请求头，需要跟uri中的一致，都是你服务的名称，否则你访问的时候，就过滤不掉头部，请求具体的api时会多一个请求头。
配置好之后，启动访问http://localhost:{port}/swagger-ui.html就可以看到swagger的页面了。其中port为你的gateway端口.

具体swagger的配置，可以网上搜索一下api，这里我贴几个大概的参考下。

1.controller的代码

    /**
     * 新增标准信息
     * @param dto 标准的dto
     * @return
     */
    @ApiOperation(value = "新增标准信息", httpMethod = "POST")
    @RequestMapping(value = "/saveStandardInfo", method = RequestMethod.POST)
    public ResponseDto saveStandardInfo(@RequestBody StandardInfoDto dto) {
        return iStandardInfoService.saveStandardInfo(dto);
    }

    /**
     * 标准信息--查看
     * @param standardId 标准的id
     * @return ResponseDto
     * <StandardInfoDto>这种写法是为了让其在swagger中展示嵌套的json值
     */
    @ApiOperation(value = "根据id查询标准信息", httpMethod = "GET")
    @RequestMapping(value = "/findStandardInfo", method = RequestMethod.GET)
    @ApiImplicitParam(name = "standardId", value = "标准id", dataType = "string")
    public ResponseDto<StandardInfoDto> findStandardInfo(@RequestParam(value = "standardId") String standardId) {
        return iStandardInfoService.findStandardInfo(standardId);
    }

    /**
     * 标准信息--修改状态
     * @param standardId    标准的id
     * @param standardState 标准的状态
     * @return
     */
    @ApiOperation(value = "修改标准信息的状态", httpMethod = "GET")
    @RequestMapping(value = "/updateStateStandardInfo", method = RequestMethod.GET)
    @ApiImplicitParams({
            @ApiImplicitParam(name = "standardId", value = "标准id", dataType = "string"),
            @ApiImplicitParam(name = "standardState", value = "标准的状态", dataType = "string", example = "1,2,3")
    })
    public ResponseDto updateStateStandardInfo(@RequestParam(value = "standardId") String standardId, @RequestParam(value = "standardState") String standardState) {
        return iStandardInfoService.updateStateStandardInfo(standardId, standardState);
    }

2.model

/**
 * @description:用于返回数据的dto
 * @Author:
 * @Date: 2019/8/15  15:46
 */
@Data
@ApiModel("返回类")
public class ResponseDto<T> {

    /**
     * 状态码
     */
    @ApiModelProperty(value = "状态码")
    private Integer code;

    /**
     * 状态信息
     */
    @ApiModelProperty(value = "状态信息")
    private String message;

    /**
     * 数据
     */
    @ApiModelProperty(value = "数据")
    private T data;

    public ResponseDto(Integer code, String message, T data) {
        this.code = code;
        this.data = data;
        this.message = message;
    }
}

这里注意就是apiModel中，可以用value,也可以用tag，但是用tag会出现多个的model，还有就是不管用tag还是value，不能出现"/"否则会报错。