Spring Boot微服务API网关配置Swagger聚合后，选择服务无法显示端点的解决方法

看起来你已经搭好了Spring Cloud Gateway + SpringDoc的Swagger聚合环境，但遇到了网关Swagger UI选服务后看不到端点的问题，我来帮你一步步排查解决~

问题根源分析 #

你当前的API网关只配置了路径分组，但没有动态拉取下游微服务的OpenAPI文档定义，同时网关也没有正确开启SpringDoc的网关聚合支持，导致Swagger UI虽然能看到服务列表，但无法加载到具体的端点信息。

具体解决步骤 #

1. 完善API网关的SpringDoc配置

首先在网关的api-gateway-dev.yml中添加SpringDoc网关支持和API文档的配置，确保网关能处理下游服务的OpenAPI请求：

springdoc:
  # 开启SpringDoc对Gateway的支持
  gateway:
    enabled: true
  # 开启网关自身的API文档（用于聚合）
  api-docs:
    enabled: true
  swagger-ui:
    path: /swagger-ui.html
    # 设置默认选中的服务（可选）
    urls-primary-name: category-microservice

2. 修改网关的OpenApiConfig，动态聚合微服务文档

你当前的OpenApiConfig只是静态分组了路径，需要改成动态发现微服务并拉取每个服务的OpenAPI定义。修改后的配置类如下：

import org.springframework.cloud.gateway.route.RouteDefinition;
import org.springframework.cloud.gateway.route.RouteDefinitionLocator;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Lazy;
import org.springdoc.core.models.GroupedOpenApi;
import reactor.core.publisher.Flux;

import java.util.ArrayList;
import java.util.List;

@Configuration
public class OpenApiConfig {

    private final RouteDefinitionLocator routeDefinitionLocator;

    // 延迟注入避免启动时依赖问题
    public OpenApiConfig(@Lazy RouteDefinitionLocator routeDefinitionLocator) {
        this.routeDefinitionLocator = routeDefinitionLocator;
    }

    @Bean
    public List<GroupedOpenApi> apis() {
        List<GroupedOpenApi> groupedApis = new ArrayList<>();
        Flux<RouteDefinition> routeDefinitions = routeDefinitionLocator.getRouteDefinitions();

        // 遍历网关所有路由，为每个微服务创建独立的OpenAPI分组
        routeDefinitions.subscribe(routeDefinition -> {
            // 从路由URI中提取服务ID（例如lb://CATEGORY-MICROSERVICE -> CATEGORY-MICROSERVICE）
            String serviceId = routeDefinition.getUri().getHost();
            if (serviceId != null && !serviceId.isBlank()) {
                String lowerCaseServiceId = serviceId.toLowerCase();
                groupedApis.add(GroupedOpenApi.builder()
                        .group(lowerCaseServiceId)
                        // 指定该分组对应的网关访问路径前缀
                        .pathsToMatch("/" + lowerCaseServiceId + "/**")
                        // 配置OpenAPI的服务器地址，指向网关的服务路由
                        .addOpenApiCustomizer(openApi -> openApi
                                .addServersItem(new io.swagger.v3.oas.models.servers.Server()
                                        .url("/" + lowerCaseServiceId)
                                        .description(serviceId + " 微服务API")))
                        .build());
            }
        });

        return groupedApis;
    }
}

3. 确保网关能访问到微服务的OpenAPI文档

你的网关已经开启了spring.cloud.gateway.discovery.locator.enabled=true，这个配置会自动为每个注册的微服务生成路由（例如/category-microservice/** 转发到 lb://CATEGORY-MICROSERVICE/**）。

先手动验证：访问 http://localhost:8080/category-microservice/v3/api-docs，如果能返回JSON格式的OpenAPI定义，说明路由正常；如果返回404，检查：

• 微服务是否已注册到服务发现组件（Eureka/Nacos等）
• 网关的lower-case-service-id=true是否生效，服务名是否转成了小写
• 微服务的v3/api-docs是否开启（SpringDoc默认开启，若需确认可在category-microservice-dev.yml添加springdoc.api-docs.enabled: true）

4. 重启服务验证

重启API网关和所有微服务后，访问http://localhost:8080/swagger-ui.html：

• 下拉选择category-microservice或user-microservice
• 此时应该能看到对应服务的所有API端点了~

额外注意点 #

• 确保所有微服务的SpringDoc版本和网关保持一致（你当前用的2.6.0是稳定版本，没问题）
• 如果你的服务发现用的不是Eureka，只需确保lb://的负载均衡逻辑正常即可
• 若不需要自动发现路由，也可以手动为每个微服务的v3/api-docs添加路由规则，例如：

- id: category-openapi
  uri: lb://CATEGORY-MICROSERVICE
  predicates:
    - Path=/v3/api-docs/category/**
  filters:
    - RewritePath=/v3/api-docs/category/(?<path>.*), /v3/api-docs/${path}

内容来源于stack exchange