在微服务大行其道到今天，服务到碎片化也带来了管理和监控的困难（统一集成网关系统在前面的sia-gateway的文章中有做分享，感兴趣的可以前往阅读）。 swagger为我们开发带来了极大到便利，但是在庞杂的系统中，即便对于开发的接入和调试，对各个分散对在线文档，也显得有些杂乱无章。即便是有如同yapi等在线文档系统，也同样需要精力去维护，而且对于文档与代码分离，同样会带来版本不一致和调试困难等问题。 在网关层集成swagger显得非常易用和优雅。但是面对各个公司不同网关配置方案，给swagger的集成带来和诸多不便和技术难题。下面我分享我在实现spring cloud gateway 集成swagger的实现方案。# 系列文章目录 提示：这里可以添加系列文章的所有文章的目录，目录需要自己手动添加

1.引入依赖包

在pom文件中添加如下依赖，推荐使用2.9.2版本

<!-- swagger 包-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

2.添加swagger配置类

@Configuration
@EnableSwagger2
@ConditionalOnProperty(name = "swagger.enable",  havingValue = "true")
public class SwaggerConfig {
 
    @Bean
    public Docket openApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("open")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.api.controller"))
                .paths(PathSelectors.any())
                .build();
    }
 
    @Bean
    public Docket adminApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("admin")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.api.controller"))
                .paths(PathSelectors.any())
                .build();
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("微服务swagger")
                .contact(new Contact("LiuChao",  "",  "liuchao332@163.com"))
                .version("1.0")
                .description("API 描述")
                .build();
    }
 
}

说明：1、此配置类为基本的swagger集成的基本配置，有些区别的是，此处配置类2个Docket元素，分别设置了不同的groupName。此操作是为了满足，将业务端和管理端分成不同的swagger页面进行展示。这个地方会为网关集成带来一些改变。不是必须要这样设置，不想将接口分开，放到同一个页面也没什么不可。 2、在配置项中需要新增swagger.enable配置，来控制是否启用swagger。

二、spring cloud gateway 集成swagger

1.spring cloud gateway搭建

spring cloud gateway 的集成非常简单，基本上实现来了开箱即用，进行简单的配置，集成eureka，就能满足我们基本的业务场景，这里就不在赘述了。

2.在网关中引入swagger包

和微服务所应用的包相同

3.添加配置类

网关的swagger集成方案与服务单元有较大不同，也更为复杂。

@Configuration
public class SwaggerConfig {
 
    @Bean
    public SecurityConfiguration securityConfiguration() {
        return SecurityConfigurationBuilder.builder().build();
    }
 
    @Bean
    public UiConfiguration uiConfiguration() {
        return UiConfigurationBuilder.builder().showExtensions(true).build();
    }
 
}

此配置类中定义SecurityConfiguration，UiConfiguration 将在下面的配置中用到这2个bean

@RestController
@RequestMapping("/swagger-resources")
public class SwaggerHandler {
 
    private final SecurityConfiguration securityConfiguration;
    private final UiConfiguration uiConfiguration;
    private final SwaggerResourcesProvider swaggerResources;
 
    @Autowired
    public SwaggerHandler(SwaggerResourcesProvider swaggerResources, SecurityConfiguration securityConfiguration, UiConfiguration uiConfiguration) {
        this.swaggerResources = swaggerResources;
        this.securityConfiguration = securityConfiguration;
        this.uiConfiguration = uiConfiguration;
    }
 
    @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<List<SwaggerResource>>> swaggerResources() {
        return Mono.just((new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK)));
    }
 
}

此类定义了swagger网关层的开放接口，在访问swagger-ui中会拉去此接口的数据。

 
```java
@Primary
@Component
@AllArgsConstructor
public class SwaggerProvider implements SwaggerResourcesProvider {
 
    public static final String SOURCE_URI = "http://%s/swagger-resources";
    private final RouteLocator routeLocator;
    private final RouteDefinitionLocator routeDefinitionLocator;
    private final RestTemplate restTemplate;
 
    @Override
    public List<SwaggerResource> get() {
        List<SwaggerResource> resources = new ArrayList<>();
        List<String> routes = new ArrayList<>();
        routeLocator.getRoutes().subscribe(route -> routes.add(route.getId()));
        routeDefinitionLocator.getRouteDefinitions()
                .filter(routeDefinition -> routes.contains(routeDefinition.getId()))
                .subscribe(routeDefinition -> routeDefinition.getPredicates().stream()
                        .filter(predicateDefinition -> ("Path").equalsIgnoreCase(predicateDefinition.getName()))
                        .forEach(predicateDefinition -> resources
                                .addAll(swaggerResource(routeDefinition))));
 
        return resources;
    }
 
    private List<SwaggerResource> swaggerResource(RouteDefinition route) {
 
        try {
            String sourceUrl = String.format(SOURCE_URI, route.getUri().getHost());
            ResponseEntity<String> content = restTemplate.getForEntity(sourceUrl, String.class);
            List<SwaggerResource> swaggerResources = JsonUtil.toList(content.getBody(), SwaggerResource.class);
 
            swaggerResources.stream().forEach(swaggerResource -> {
                swaggerResource.setName(route.getUri().getHost().toLowerCase() + "-" + swaggerResource.getName());
                swaggerResource.setUrl("/" + route.getUri().getHost().toLowerCase() + swaggerResource.getUrl());
            });
 
            return swaggerResources;
        } catch (Exception e) {
            return new ArrayList<>();
        }
    }
}

这个类是核心，这个类封装的是SwaggerResource，即在swagger-ui.html页面中顶部的选择框，选择服务的swagger页面内容。 RouteLocator：获取spring cloud gateway中注册的路由 RouteDefinitionLocator：获取spring cloud gateway路由的详细信息 RestTemplate：获取各个配置有swagger的服务的swagger-resources

三、私货

在一般的情况下，网关一般使用一个服务，一个路由的配置方式，我也建议大家这么使用，这样管理控制都非常灵活。但在项目中，也遇到过一种特别的配置方式。如下：

routes:
   - id: remove_api_prefix
     uri: http://127.0.0.1:80
     order: 1
     predicates:
       - Path=/api/**
     filters:
       - StripPrefix=1

按照这种配置方式，在请求url前加上/api前缀，网关在收到此类请求后，将api截取掉，在转发给自己；网关再次收到没有api的请求后，对请求第二级目录按服务名进行路由。 这种方式可以将在注册中心注册对服务都暴露到网关到路由中，就不需要对每个服务配置路由规则。 对于新加的服务，也不行要配置新的路由。

但是这样也引起了新的问题，在swagger的baseUrl，出现了,符号

www.example-gateway.com/api,/example-service/

且通过swagger发送的请求，在url上都出现了,。导致不能够请求到正确到地址上，然后就开始分析这个,的来源。

curl -X POST “http://www.example-gateway.com/api,/example-service/user/info” -H “accept: /”

1.分析一

初步可以判断，这个符号肯定和这种特殊的路由方式有关系，因为在使用一服务一路由的配置方式的时候，并没有这个问题。从哪里入手呢，还是从服务的swagger页面入手，因为这个符号就来自这里。 如上截图，在api-docs接口中所返回的数据里，basePath就已经带上里这个符号。有了一个初步的定位思路，从swagger的api-docs接口入手。

2.分析二

在找到swagger接口源头，往下debug，终于在XForwardPrefixPathAdjuster类中发现类这个符号出现的地方。源码如下图，

public class XForwardPrefixPathAdjuster implements PathAdjuster {
    static final String X_FORWARDED_PREFIX = "X-Forwarded-Prefix";
    private final HttpServletRequest request;
 
    public XForwardPrefixPathAdjuster(HttpServletRequest request) {
        this.request = request;
    }
 
    public String adjustedPath(String path) {
        String prefix = this.request.getHeader("X-Forwarded-Prefix");
        if (prefix != null) {
            return !SpringVersionCapability.supportsXForwardPrefixHeader(SpringVersion.getVersion()) ? prefix + path : prefix;
        } else {
            return path;
        }
    }
}

本以为发现源头，但是在debug的过程中，到这里接收到http头的X-Forwarded-Prefix参数，已经带有这个符号。 由此可以判断，在swagger接收到到http请求就已经带有这个符号。所以只能往上找原因。那就只有一个地方了，问题出在网关。

3.分析三

然后我就开始spring-cloud-gateway-core-2.2.2.RELEASE.jar包里，找什么地方在封装header的X-Forwarded-Prefix参数。有赖于spring合理的代码和包结构，没用多少时间就找到XForwardedHeadersFilter类，如下所示：

private void updateRequest(HttpHeaders updated, URI originalUri, String originalUriPath, String requestUriPath) {
        if (requestUriPath != null && originalUriPath.endsWith(requestUriPath)) {
            String prefix = substringBeforeLast(originalUriPath, requestUriPath);
            if (prefix != null && prefix.length() > 0 && prefix.length() <= originalUri.getPath().length()) {
                this.write(updated, "X-Forwarded-Prefix", prefix, this.isPrefixAppend());
            }
        }
 
    }

在此方法，完成的header头的X-Forwarded-Prefix的封装。再往下看write方法

private void write(HttpHeaders headers, String name, String value, boolean append) {
        if (append) {
            headers.add(name, value);
            List<String> values = headers.get(name);
            String delimitedValue = StringUtils.collectionToCommaDelimitedString(values);
            headers.set(name, delimitedValue);
        } else {
            headers.set(name, value);
        }
 
    }

在这里，当网关在截取掉api，再发送给自己，这个地方就会在此请求中，List会将这个请求头中封装两次的X-Forwarded-Prefix，/api和/example-service。

StringUtils.collectionToCommaDelimitedString(values)

方法将它们拼接到一起，就产生了,符号。如今要想办法消除掉这个符号。灵机一动，在写个filer，将,干掉就行了。

4.解决

添加一个global filter，删除X-Forwarded-Prefix参数到,符号。完美解决。

@Component
public class XForwardedPrefixFilter implements HttpHeadersFilter, Ordered {
 
    @Override
    public HttpHeaders filter(HttpHeaders input, ServerWebExchange exchange) {
        List<String> xForwareds = input.get("X-Forwarded-Prefix");
        String forward = xForwareds.get(0);
        if (forward.contains(",")) {
            forward = forward.replaceAll(",", "/");
        }
 
        input.set("X-Forwarded-Prefix", forward);
        return input;
    }
 
    @Override
    public int getOrder() {
        return 1;
    }
}