Spring Cloud 项目在网关聚合 Swagger 文档

Spring Cloud 项目在网关聚合 Swagger 文档

示例代码：Gitee 仓库 中的

项目	说明
swagger-2-sample-knife4j-cloud	swagger 请求走网关

各个微服务的改动

改动一：新增依赖

<dependency>  
    <groupId>com.github.xiaoymin</groupId>  
    <artifactId>knife4j-micro-spring-boot-starter</artifactId>  
    <version>${knife4j.version}</version>  <!-- 3.0.3 -->
    <exclusions>  
        <exclusion>  
            <groupId>javax.validation</groupId>  
            <artifactId>validation-api</artifactId>  
        </exclusion>  
    </exclusions>  
</dependency>

改动二：新增配置类

  
@Configuration  
@EnableOpenApi  
@RequiredArgsConstructor  
public class SwaggerConfiguration {  
  
    private final OpenApiExtensionResolver openApiExtensionResolver;  
  
    @Value("${spring.application.name}")  
    private String applicationName;  
  
    @Bean  
    @Order(value = 1)  
    public Docket docDocket() {  
        return new Docket(DocumentationType.OAS_30)  
                .pathMapping("/" + applicationName) // ==> /department-service  
                .enable(true)  
                .apiInfo(groupApiInfo())  
                .select()  
                .apis(RequestHandlerSelectors.withMethodAnnotation(Operation.class))  
                .paths(PathSelectors.any())  
                .build()  
                .extensions(openApiExtensionResolver.buildExtensions("部门微服务"))  
                ;  
    }  
  
    private ApiInfo groupApiInfo() {  
        return new ApiInfoBuilder()  
                .title("Knife4j接口文档")  
                .description("Knife4j接口文档")  
                .termsOfServiceUrl("https://doc.xiaominfo.com/")  
                .version("1.0.0")  
                .build();  
    }
}

关键项说明

上述内容，无论是 pom 引包，还是加配置类，绝大部分内容都是复制粘贴，无需改动的。

但是在配置类中，有一个信息必须注意，它必须和你的 spring-cloud 的配置相关：

.pathMapping("/" + applicationName) 

.pathMapping() 方法的的值是你的请求通过网关时“必要的前缀”。

换句话说，一个请求经过网关之后，为了确保要能够被网关“转”到你的当前微服务中，网关所收到的请求 URI 中的前缀必须是一个特定的、约定好的内容。

在这里（默认情况下），我们都是以微服务的服务名作为前缀。这个值，就是项目配置文件中的 spring.application.name 配置项的值。

所以，（不出意外的话）：

• 如果是 xxx-service 的 Swagger 配置，这里的 .pathMapping() 方法的值应该是 “/xxx-service”；
• 如果是 yyy-service 的 Swagger 配置，这里的 .pathMapping() 方法的值应该是 “/yyy-service”；
• 如果是 zzz-service 的 Swagger 配置，这里的 .pathMapping() 方法的值应该是 “/zzz-service”。

Gateway 的改动

改动一：新增依赖

<dependency>  
    <groupId>com.github.xiaoymin</groupId>  
    <artifactId>knife4j-spring-boot-starter</artifactId>  
    <version>${knife4j.version}</version>  <!-- 3.0.3 -->
</dependency>

改动二：新增配置类和处理类

提示：以下三个类你可以专门放在一个 swagger 包中进行统一管理。

@Component  
public class SwaggerHeaderFilter extends AbstractGatewayFilterFactory {  
        private static final String HEADER_NAME = "X-Forwarded-Prefix";  
  
        private static final String URI = "/v3/api-docs";  
  
        @Override  
        public GatewayFilter apply(Object config) {  
            return (exchange, chain) -> {  
                ServerHttpRequest request = exchange.getRequest();  
                String path = request.getURI().getPath();  
                if (!StringUtils.endsWithIgnoreCase(path,URI )) {  
                    return chain.filter(exchange);  
                }  
                String basePath = path.substring(0, path.lastIndexOf(URI));  
                ServerHttpRequest newRequest = request.mutate().header(HEADER_NAME, basePath).build();  
                ServerWebExchange newExchange = exchange.mutate().request(newRequest).build();  
                return chain.filter(newExchange);  
            };  
        }  
}

@Primary  
@Configuration  
@RequiredArgsConstructor  
public class SwaggerResourceConfig implements SwaggerResourcesProvider {  
  
    private final RouteLocator routeLocator;  
    private final GatewayProperties gatewayProperties;  
  
    @Override  
    public List<SwaggerResource> get() {  
        List<SwaggerResource> resources = new ArrayList<>();  
        List<String> routes = new ArrayList<>();  
        routeLocator.getRoutes().subscribe(route -> routes.add(route.getId()));  
  
        // resources为所有路由都加载到文档，如果需要部分显示，在下方使用filter进行过滤即可  
        gatewayProperties.getRoutes().stream().filter(routeDefinition -> routes.contains(routeDefinition.getId())).forEach(route -> {  
            route.getPredicates().stream()  
                    .filter(predicateDefinition -> ("Path").equalsIgnoreCase(predicateDefinition.getName()))  
                    .forEach(predicateDefinition -> resources.add(swaggerResource(route.getId(),  
                            predicateDefinition.getArgs().get(NameUtils.GENERATED_NAME_PREFIX + "0")  
                                    .replace("**", "v3/api-docs"))));  
        });  
        return resources;  
    }  
  
    private SwaggerResource swaggerResource(String name, String url) {  
        SwaggerResource swaggerResource = new SwaggerResource();  
        swaggerResource.setName(name);  
        swaggerResource.setLocation(url);  
        swaggerResource.setUrl(url);  
        swaggerResource.setSwaggerVersion("3.0");  
        return swaggerResource;  
    }  
  
}

@RestController  
public class SwaggerHandler {  
  
    @Qualifier  
    private final SwaggerResourcesProvider swaggerResources;  
  
    public SwaggerHandler(SwaggerResourcesProvider swaggerResources) {  
        this.swaggerResources = swaggerResources;  
    }  
  
    @GetMapping("/swagger-resources")  
    public Mono<ResponseEntity<List<SwaggerResource>>> swaggerResources() {  
        return Mono.just((new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK)));  
    }  
  
}

以上三个新增代码都不需要做任何改动。

改动三：改动配置文件

本来，我们的网关项目的配置文件中有个配置项：

spring:
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true

这个配置项“帮”我们省略掉了大段的、啰嗦的配置简化了配置文件的内容。

但是，出人意料的是：它对我们引入的 Swagger/Knife4j 无效！

所以，如果我们需要网关处引入 Swagger，用以聚合各个微服务的 Swagger，那么，我们需要把这个简写配置项还原成以前大段的、啰嗦的写法…

例如：

spring:  
  cloud:  
    gateway:  
      routes:  
        - id: 部门微服务  
          uri: lb://department-service
          predicates:  
            - Path=/department-service/**
          filters:  
            - RewritePath=/department-service/(?<segment>.*), /${segment} 
        - id: 员工微服务  
          uri: lb://employee-service  
          predicates:  
            - Path=/employee-service/**  
          filters:  
            - RewritePath=/employee-service/(?<segment>.*), /${segment}

上面的配置内容，就是以前被一个配置项简化掉的、现在需要再还原回来的内容。它的意思是：

• 当网关收到以 /department-service/ 开头的请求，就“转给” department-service，并且将请求 URI 前段的 /department-service/ 部分截去。

• 当网关收到以 /employee-service/ 开头的请求，就“转给” employee-service，并且将请求 URI 前段的 /department-service/ 部分截去。