Spring Boot 3 WebFlux集成SpringDoc后Swagger页面空白求助

1. 确认访问路径是否正确 #

SpringDoc 2.x 配合 WebFlux 时，默认的 Swagger UI 访问路径已调整为 http://localhost:9079/swagger-ui/index.html（需包含末尾的 index.html），旧路径 swagger-ui.html 可能因重定向逻辑导致空白页。

2. 检查依赖兼容性 #

Spring Boot 3.x 要求 SpringDoc 版本至少为 2.0.0+，你使用的 2.1.0 版本是兼容的，若问题仍存在，可尝试升级至最新稳定版（如 2.2.0）规避适配问题。

3. 补充基础配置 #

若路径无误仍显示空白，需在配置文件中添加基础配置，确保 SpringDoc 能正确扫描 WebFlux 控制器：

application.yml 示例： #

springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    # 可选：指定控制器所在包路径，确保接口被识别
    packages-to-scan: com.your.project.controller

application.properties 示例： #

springdoc.api-docs.enabled=true
springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.enabled=true
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.packages-to-scan=com.your.project.controller

4. 排查静态资源拦截问题 #

若项目存在自定义 WebFilter、网关过滤器或 Spring Security 配置，需放行 Swagger 相关资源路径：

• 允许访问 /swagger-ui/**、/v3/api-docs/**、/webjars/** 路径
• Spring Security 配置示例：

@Configuration
public class SecurityConfig {
    @Bean
    public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
        return http
                .authorizeExchange(exchanges -> exchanges
                        .pathMatchers("/swagger-ui/**", "/v3/api-docs/**", "/webjars/**")
                        .permitAll()
                        .anyExchange()
                        .authenticated()
                )
                .build();
    }
}

5. 验证API文档生成状态 #

先访问 http://localhost:9079/v3/api-docs，若能返回 JSON 格式的 API 文档数据，说明接口解析正常，问题仅出在 Swagger UI 渲染环节；若返回404，需检查 packages-to-scan 配置是否正确，或控制器是否添加了 @RestController、@GetMapping 等注解。

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