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-servicepredicates:  - 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/ 部分截去。