Spring Boot3升级springdoc-openapi后Swagger UI加载配置失败求助

核心问题分析 #

你能正常访问/api/v3/api-docs但Swagger UI提示"Failed to load remote configuration"，主要是请求路径不匹配或Security拦截导致，结合你的配置按以下步骤修复：

1. 更新Spring Security白名单 #

你的API部署在/api上下文路径下，但当前白名单未包含该前缀，导致Swagger UI相关请求被拦截。替换白名单配置：

private static final String[] WHITELIST = {
        // springdoc-openapi 必需端点
        "/api/v3/api-docs/**",
        "/api/swagger-ui/**",
        "/api/swagger-ui.html",
        "/api/webjars/**"
};

注：如果你的server.servlet.context-path=/api，也可以保持白名单路径不带前缀，但显式加上前缀更不容易出错。

2. 修正GroupedOpenApi包扫描 #

你当前的packagesToScan("org.springframework.boot")完全错误，这会扫描Spring Boot自身的包，根本不会生成你的业务接口文档。改成自己的控制器所在包：

@Bean
public GroupedOpenApi apiDescription() {
    return GroupedOpenApi.builder()
            .group("Service")
            .pathsToMatch("/**")
            .packagesToScan("com.yourcompany.yourproject.controller") // 替换成你的实际包路径
            .build();
}

3. 配置Swagger UI的文档地址 #

Swagger UI默认请求/v3/api-docs，但你的文档地址是/api/v3/api-docs，需要在配置文件中指定：

application.properties

springdoc.swagger-ui.url=/api/v3/api-docs

application.yml

springdoc:
  swagger-ui:
    url: /api/v3/api-docs

4. 确保Security允许匿名访问白名单 #

检查你的SecurityFilterChain配置，确保白名单路径被放行：

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(auth -> auth
            .requestMatchers(WHITELIST).permitAll()
            .anyRequest().authenticated()
        )
        // 其他Security配置（如OAuth2、CSRF等）...
    return http.build();
}

验证流程 #

1. 重启应用，确认https://address/api/v3/api-docs能返回正常的JSON文档
2. 访问https://address/api/swagger-ui/index.html，检查页面是否加载成功并显示你的业务接口
3. 若仍有问题，打开浏览器控制台查看具体错误（如403/404），针对性排查

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