Spring Boot 3.1.9集成springdoc-openapi遇白标错误页求助

针对你在Spring Boot 3.1.9中集成SpringDoc OpenAPI（springdoc-openapi-starter-webmvc-ui:2.2.0）后出现白标错误的问题，可按以下步骤排查：

1. 清理依赖冲突 #

执行./gradlew dependencies查看项目依赖树，确认是否存在旧版Swagger（如SpringFox）或冲突的OpenAPI依赖残留。若有冲突，在依赖声明中排除冲突模块：

implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0") {
    // 示例：排除冲突的swagger注解依赖
    exclude group: 'io.swagger.core.v3', module: 'swagger-annotations'
}

2. 验证自动配置是否生效 #

在application.properties或application.yml中添加日志配置，查看SpringDoc相关组件是否正常加载：

logging.level.org.springdoc=DEBUG

启动项目后，检查日志中是否存在SpringDocConfiguration、SwaggerUiWebMvcConfigurer等类的初始化日志。若没有，说明自动配置未生效，需检查是否在@SpringBootApplication中排除了相关自动配置类。

3. 放行Swagger静态资源 #

若项目自定义了WebMvcConfigurer，需确保Swagger UI的静态资源路径被正确映射：

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/swagger-ui/");
        registry.addResourceHandler("/v3/api-docs/**")
                .addResourceLocations("classpath:/META-INF/resources/v3/api-docs/");
    }
}

4. 确认正确的访问路径 #

SpringDoc 2.x在Spring Boot 3中的默认访问路径为：

• Swagger UI：http://localhost:8080/swagger-ui/index.html
• API文档：http://localhost:8080/v3/api-docs

若项目配置了server.servlet.context-path，需在路径前加上上下文前缀。也可通过配置自定义UI路径：

springdoc.swagger-ui.path=/my-swagger

此时访问路径为http://localhost:8080/my-swagger

5. 排除拦截器对Swagger路径的拦截 #

若项目存在自定义拦截器，需将Swagger相关路径加入排除列表：

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new CustomInterceptor())
                .excludePathPatterns("/swagger-ui/**", "/v3/api-docs/**");
    }
}

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