Spring Boot微服务配置Swagger遇404错误，求解决方法

针对你遇到的通过Gateway访问聚合Swagger出现404的问题，按以下步骤排查修复：

1. 修正Gateway的SpringDoc依赖 #

Spring Cloud Gateway基于WebFlux栈，你当前添加的springdoc-openapi-starter-webmvc-ui是适配Servlet/MVC的，必须换成WebFlux版本：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.0.0</version>
</dependency>

同时，**所有业务微服务（Elemental Service、Chat Service）**都要添加对应栈的SpringDoc依赖：

• 若微服务是Spring MVC（Servlet栈）：保留你原有的springdoc-openapi-starter-webmvc-ui
• 若微服务是WebFlux栈：使用和Gateway一致的springdoc-openapi-starter-webflux-ui

2. 配置Gateway路由转发Swagger请求 #

在Gateway的配置文件（application.yml）中添加路由规则，让Swagger文档请求能正确转发到对应微服务：

spring:
  cloud:
    gateway:
      routes:
        # Elemental Service Swagger路由
        - id: elemental-service-swagger
          uri: lb://ELEMENTAL-SERVICE # 替换为服务在注册中心的名称
          predicates:
            - Path=/elemental-service/v3/api-docs/**
          filters:
            - RewritePath=/elemental-service/v3/api-docs/(?<path>.*), /v3/api-docs/${path}
        # Chat Service Swagger路由
        - id: chat-service-swagger
          uri: lb://CHAT-SERVICE # 替换为服务在注册中心的名称
          predicates:
            - Path=/chat-service/v3/api-docs/**
          filters:
            - RewritePath=/chat-service/v3/api-docs/(?<path>.*), /v3/api-docs/${path}

注意：ELEMENTAL-SERVICE、CHAT-SERVICE必须和对应微服务的spring.application.name配置完全一致。

3. 配置Gateway的Swagger聚合逻辑 #

创建Gateway的Swagger配置类，自动从注册中心发现所有微服务的OpenAPI文档：

import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.cloud.gateway.route.RouteDefinitionLocator;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    private final RouteDefinitionLocator routeDefinitionLocator;

    public OpenApiConfig(RouteDefinitionLocator routeDefinitionLocator) {
        this.routeDefinitionLocator = routeDefinitionLocator;
    }

    @Bean
    public GroupedOpenApi allServicesApi() {
        return GroupedOpenApi.builder()
                .group("all-services")
                .pathsToMatch("/**")
                .build();
    }
}

同时在Gateway的配置文件中开启SpringDoc网关支持：

springdoc:
  api-docs:
    enabled: true
  gateway:
    enabled: true
    routes-to-match: /elemental-service/**, /chat-service/**

4. 验证访问路径与端口 #

确认Gateway的server.port配置为8080，访问时使用完整路径：http://localhost:8080/swagger-ui/index.html（部分版本中/swagger-ui/会出现重定向失败，需显式指定index.html）。

5. 放行Swagger相关路径（若有Spring Security） #

如果Gateway或微服务启用了Spring Security，必须放行Swagger相关路径，避免被拦截：

Servlet栈（Spring MVC）Security配置 #

@Override
protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests()
            .antMatchers("/swagger-ui/**", "/v3/api-docs/**", "/elemental-service/v3/api-docs/**", "/chat-service/v3/api-docs/**")
            .permitAll()
            .anyRequest()
            .authenticated();
}

WebFlux栈Security配置 #

@Override
public void configure(ServerHttpSecurity http) {
    http.authorizeExchange()
            .pathMatchers("/swagger-ui/**", "/v3/api-docs/**", "/elemental-service/v3/api-docs/**", "/chat-service/v3/api-docs/**")
            .permitAll()
            .anyExchange()
            .authenticated();
}

6. 单独验证微服务的Swagger文档 #

先直接访问每个微服务的/v3/api-docs（比如http://localhost:xxxx/v3/api-docs，xxxx为微服务端口），确认能返回JSON格式的文档，确保单个服务的SpringDoc配置正常，再通过Gateway聚合访问。

内容的提问来源于stack exchange，提问作者Simone Campisi