Spring Boot 3.2.5集成springdoc-ui 2.5.0时Swagger页面加载失败

1. 确认依赖正确性 #

确保只引入WebFlux版本的SpringDoc starter，不要混入Servlet环境的依赖：

<!-- 正确的WebFlux依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.5.0</version>
</dependency>

检查pom.xml或build.gradle，避免同时存在springdoc-openapi-starter-webmvc-ui这类Servlet版本的依赖。

2. 修正application.yaml配置 #

明确指定SpringDoc的API文档路径和Swagger UI的配置，覆盖默认的错误路径：

springdoc:
  api-docs:
    path: /v3/api-docs  # 强制指定标准OpenAPI文档路径
  swagger-ui:
    config-url: /v3/api-docs/swagger-config  # 告诉UI配置文件的位置
    url: /v3/api-docs  # 指定UI加载的API文档源

如果你的应用设置了server.base-path（Spring Boot 3+的上下文路径），比如/api，要把路径改成/api/v3/api-docs，同时对应调整swagger-ui的配置项。

3. 完善SecurityWebFilterChain配置 #

即使允许所有请求，也要明确放行Swagger相关路径和静态资源，同时关闭CSRF：

@Bean
public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
    return http
            .authorizeExchange(exchanges -> exchanges
                    .pathMatchers("/webjars/**", "/v3/api-docs/**", "/swagger-ui/**", "/api/v1/mystuff/**")
                    .permitAll()
                    .anyExchange().authenticated()
            )
            .csrf(ServerHttpSecurity.CsrfSpec::disable)  // WebFlux环境下Swagger需要关闭CSRF
            .build();
}

重点放行/webjars/**（Swagger UI静态资源）、/v3/api-docs/**（API文档及配置），避免请求被拦截。

4. 手动注册OpenAPI Bean #

若自动配置未触发，手动创建OpenAPI Bean确保文档生成：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("My Stuff API")
                        .version("v1")
                        .description("Simple API for my stuff"));
    }
}

5. 验证步骤 #

1. 启动应用后，直接访问http://localhost:8090/v3/api-docs，若返回JSON格式的OpenAPI文档，说明文档生成正常。
2. 再访问http://localhost:8090/webjars/swagger-ui/index.html，此时应该能正常加载UI并显示你的API。

如果仍出现404，检查是否有自定义WebFilter或Gateway路由拦截了请求，或者Spring Boot自动配置被意外排除（比如@SpringBootApplication的exclude属性）。

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