Spring Cloud Gateway整合Swagger3 OpenAPI失效求助

核心问题1：GroupedOpenApi未被正确注册 #

你的Swagger配置中，构建的GroupedOpenApi实例没有添加到返回的groups列表中，导致Spring容器无法识别这些分组API，Swagger UI也就无法加载各微服务的文档。

修正后的Swagger配置 #

@Bean
@Lazy(false)
public List<GroupedOpenApi> apis(SwaggerUiConfigParameters swaggerUiConfigParameters, RouteDefinitionLocator locator) {
    List<GroupedOpenApi> groups = new ArrayList<>();
    List<RouteDefinition> definitions = locator.getRouteDefinitions().collectList().block();
    
    definitions.stream()
            .filter(routeDefinition -> routeDefinition.getId().matches(".*-service"))
            .forEach(routeDefinition -> {
                String name = routeDefinition.getId().replaceAll("-service", "");
                swaggerUiConfigParameters.addGroup(name);
                // 将构建好的GroupedOpenApi实例添加到列表中
                GroupedOpenApi groupedApi = GroupedOpenApi.builder()
                        .pathsToMatch("/" + name + "/**")
                        .group(name)
                        .build();
                groups.add(groupedApi);
            });
    return groups;
}

核心问题2：Gateway路由顺序与规则问题 #

当前路由配置中，system-service路由在openapi路由之前，可能导致/v3/api-docs/system这类请求被先匹配到/system/**规则，无法正确转发到openapi路由。需要调整路由顺序，让openapi路由优先匹配。

修正后的Gateway配置 #

spring:
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true
      routes:
        # 优先配置openapi路由，避免被其他服务路由拦截
        - id: openapi
          uri: http://localhost:${server.port}
          predicates:
            - Path=/v3/api-docs/**
          filters:
            - RewritePath=/v3/api-docs/(?<path>.*), /${path}/v3/api-docs
        - id: system-service
          uri: lb://system-service
          predicates:
            - Path=/system/**
          filters:
            - RewritePath=/system/(?<path>.*), /${path}

额外检查项 #

1. 依赖完整性：确保Gateway项目引入了正确的springdoc依赖（对应v1.6.12版本）

<!-- Maven依赖示例 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-gateway</artifactId>
    <version>1.6.12</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-webflux-ui</artifactId>
    <version>1.6.12</version>
</dependency>

2. 微服务自身Swagger可用性：单独访问每个微服务的/v3/api-docs端点，确认能正常返回OpenAPI文档，排除微服务自身配置问题。
3. Security路径匹配：验证whiteListSwagger中的路径是否覆盖了所有Swagger相关端点，WebFlux的路径匹配是精确匹配前缀，当前配置的/v3/api-docs/**、/swagger-ui/**等规则是正确的。

内容的提问来源于stack exchange，提问作者Minh Trần