Spring Cloud.Finchley版 Gateway整合Swagger聚合微服务系统API文档

短命女 2022-12-27 04:51 125阅读 0赞

# 一、概述  #

**版本说明**：SpringBoot2：2.0.5.RELEASE，Spring Cloud.Finchley版；

**说明**：Spring Cloud Gateway替换Zuul的时候发现Swagger并不支持以WebFlux为底层的Gateway，无法集成，运行报错;

# 二、网关配置 #

## 2.1 pom文件: ##

<dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-starter-gateway</artifactId>
                <exclusions>
                    <exclusion>
                        <groupId>org.springframework.boot</groupId>
                        <artifactId>spring-boot-starter-web</artifactId>
                    </exclusion>
                </exclusions>
            </dependency>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
            </dependency>
    
            
            
            
            
            
    
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-test</artifactId>
                <scope>test</scope>
            </dependency>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
            </dependency>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-actuator</artifactId>
            </dependency>
            <dependency>
                <groupId>com.alibaba</groupId>
                <artifactId>fastjson</artifactId>
                <version>1.2.58</version>
            </dependency>
            
            <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <scope>provided</scope>
            </dependency>
            
            <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>
            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>swagger-bootstrap-ui</artifactId>
                <version>1.9.3</version>
            </dependency>
        </dependencies>

##  2.2 网关properties.yml文件: ##

spring:
      profiles:
        active: dev
      application:
        name: gateway-service
      cloud:
        gateway:
          discovery:
            locator:
              enabled: true
              # 服务名小写
              lower-case-service-id: true
          routes:
            - id: sso-service
              # lb代表从注册中心获取服务，且已负载均衡方式转发
              uri: lb://sso-service
              predicates:
                - Path=/sso/**
              # 加上StripPrefix=1，否则转发到后端服务时会带上consumer前缀
              filters:
                - SwaggerHeaderFilter
                - StripPrefix=1
                - AddResponseHeader=X-Response-Default-Foo, Default-Bar
            - id: sys-service
              # lb代表从注册中心获取服务，且已负载均衡方式转发
              uri: lb://sys-service
              predicates:
                - Path=/sys/**
                # 加上StripPrefix=1，否则转发到后端服务时会带上consumer前缀
              filters:
                - SwaggerHeaderFilter
                - StripPrefix=1
            # 路由到百度页面
            - id: baidu_route
              uri: http://www.baidu.com
              predicates:
                - Path=/baidu/**
              filters:
                - SwaggerHeaderFilter
                - StripPrefix=1

# 三、关键代码 #

## 3.1 SwaggerHandler.java ##

**说明：**因为Gateway里没有配置SwaggerConfig，而运行Swagger-ui又需要依赖一些接口，所以我的想法是自己建立相应的swagger-resource端点。

import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.http.HttpStatus;
    import org.springframework.http.ResponseEntity;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    import reactor.core.publisher.Mono;
    import springfox.documentation.swagger.web.*;
    
    import java.util.Optional;
    
    @RestController
    @RequestMapping("/swagger-resources")
    public class SwaggerHandler {
        @Autowired(required = false)
        private SecurityConfiguration securityConfiguration;
        @Autowired(required = false)
        private UiConfiguration uiConfiguration;
        private final SwaggerResourcesProvider swaggerResources;
    
        @Autowired
        public SwaggerHandler(SwaggerResourcesProvider swaggerResources) {
            this.swaggerResources = swaggerResources;
        }
    
    
        @GetMapping("/configuration/security")
        public Mono<ResponseEntity<SecurityConfiguration>> securityConfiguration() {
            return Mono.just(new ResponseEntity<>(
                    Optional.ofNullable(securityConfiguration).orElse(SecurityConfigurationBuilder.builder().build()), HttpStatus.OK));
        }
    
        @GetMapping("/configuration/ui")
        public Mono<ResponseEntity<UiConfiguration>> uiConfiguration() {
            return Mono.just(new ResponseEntity<>(
                    Optional.ofNullable(uiConfiguration).orElse(UiConfigurationBuilder.builder().build()), HttpStatus.OK));
        }
    
        @GetMapping("")
        public Mono<ResponseEntity> swaggerResources() {
            return Mono.just((new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK)));
        }
    }

## 3.2 SwaggerProvider.java ##

**说明：**因为Swagger暂不支持webflux项目，所以Gateway里不能配置SwaggerConfig，也就是说Gateway无法提供自身API。所以这里的集成只是基于基于WebMvc的微服务项目。

**配置SwaggerProvider，获取Api-doc，即SwaggerResources。**

import lombok.AllArgsConstructor;
    import org.springframework.cloud.gateway.support.NameUtils;
    import org.springframework.context.annotation.Primary;
    import org.springframework.stereotype.Component;
    import springfox.documentation.swagger.web.SwaggerResource;
    import springfox.documentation.swagger.web.SwaggerResourcesProvider;
    import org.springframework.cloud.gateway.config.GatewayProperties;
    import org.springframework.cloud.gateway.route.RouteLocator;
    
    import java.util.ArrayList;
    import java.util.List;
    
    
    
    /**
     * @ClassName: SwaggerProvider
     * @Description: 聚合接口文档注册
     **/
    @Component
    @Primary
    @AllArgsConstructor
    public class SwaggerProvider implements SwaggerResourcesProvider {
        //v2/api-docs
        public static final String API_URI = "/v2/api-docs";
        private final RouteLocator routeLocator;
        private final GatewayProperties gatewayProperties;
    
    
        @Override
        public List<SwaggerResource> get() {
            List<SwaggerResource> resources = new ArrayList<>();
            List<String> routes = new ArrayList<>();
            /**
             * 获取Gateway配置文件的route参数
             */
            routeLocator.getRoutes().subscribe(route -> routes.add(route.getId()));
            /**
             * 结合配置的route-path和route过滤，只获取有效的route节点
             */
            gatewayProperties.getRoutes().stream().filter(routeDefinition -> routes.contains(routeDefinition.getId()))
                    .forEach(routeDefinition -> routeDefinition.getPredicates().stream()
                            .filter(predicateDefinition -> ("Path").equalsIgnoreCase(predicateDefinition.getName()))
                            .forEach(predicateDefinition -> resources.add(swaggerResource(routeDefinition.getId(),
                                    predicateDefinition.getArgs().get(NameUtils.GENERATED_NAME_PREFIX + "0")
                                            .replace("/**", API_URI)))));
    
            return resources;
        }
    
        private SwaggerResource swaggerResource(String name, String location) {
            SwaggerResource swaggerResource = new SwaggerResource();
            swaggerResource.setName(name);
            swaggerResource.setLocation(location);
            swaggerResource.setSwaggerVersion("2.0");
            return swaggerResource;
        }
    }

## 3.3 SwaggerHeaderFilter.java ##

说明：**【Spring Boot版本超过2.0.6的应该可以跳过这一步，最新源码也更新了。Spring修复了bug给我们添加上了这个Header】**另外，我发现在路由为sys/test/\{a\}/\{b\}，在swagger会显示为test/\{a\}/\{b\}，缺少了sys这个路由节点。断点源码时发现在Swagger中会根据**X-Forwarded-Prefix**这个Header来获取BasePath，将它添加至接口路径与host中间，这样才能正常做接口测试，而Gateway在做转发的时候并没有这个Header添加进Request，所以发生接口调试的404错误。解决思路是在Gateway里加一个过滤器来添加这个header。

import org.springframework.cloud.gateway.filter.GatewayFilter;
    import org.springframework.cloud.gateway.filter.factory.AbstractGatewayFilterFactory;
    import org.springframework.http.server.reactive.ServerHttpRequest;
    import org.springframework.stereotype.Component;
    import org.springframework.util.StringUtils;
    import org.springframework.web.server.ServerWebExchange;
    
    
    @Component
    public class SwaggerHeaderFilter extends AbstractGatewayFilterFactory {
        private static final String HEADER_NAME = "X-Forwarded-Prefix";
    
        @Override
        public GatewayFilter apply(Object config) {
            return (exchange, chain) -> {
                ServerHttpRequest request = exchange.getRequest();
                String path = request.getURI().getPath();
                if (!StringUtils.endsWithIgnoreCase(path, SwaggerProvider.API_URI)) {
                    return chain.filter(exchange);
                }
                String basePath = path.substring(0, path.lastIndexOf(SwaggerProvider.API_URI));
                ServerHttpRequest newRequest = request.mutate().header(HEADER_NAME, basePath).build();
                ServerWebExchange newExchange = exchange.mutate().request(newRequest).build();
                return chain.filter(newExchange);
            };
        }
    }

# 四、访问 #

这时启动Gateway，访问gateway-ip:gateway-port/doc.html时，即可正常使用swagger；