Spring Boot 3集成Spring Security后Open API文档返回空的问题

针对Spring Boot 3.3.5集成springdoc-openapi-starter-webmvc-api 2.6.0后，/v3/api-docs返回空响应的问题，可按以下步骤排查：

1. 确保springdoc自动配置类被加载 #

如果Spring Security的配置或其他自动配置逻辑意外排除了springdoc的配置，可在你的Security配置类上显式导入SpringDocConfiguration：

@Configuration
@EnableWebSecurity
@EnableMethodSecurity(securedEnabled = true, jsr250Enabled = true)
@Import(SpringDocConfiguration.class)
public class SecurityConfig {
    // 你的现有配置代码
}

2. 排除JWT过滤器对文档路径的拦截 #

你的JWT认证过滤器可能拦截了/v3/api-docs请求，需要在过滤器中添加路径排除逻辑：

public class JwtAuthenticationFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        String path = request.getRequestURI();
        // 跳过文档相关路径
        if (path.startsWith("/v3/api-docs")) {
            filterChain.doFilter(request, response);
            return;
        }
        // 原有JWT校验逻辑
    }
}

3. 显式配置OpenAPI Bean #

手动创建OpenAPI实例，确保文档元数据被正确初始化：

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("项目API文档")
                    .version("1.0")
                    .description("项目接口的OpenAPI规范文档"));
}

4. 检查上下文路径配置 #

如果项目设置了server.servlet.context-path，需确保springdoc的路径配置匹配：
在application.properties/yaml中添加：

springdoc.api-docs.path=/v3/api-docs

（如果上下文路径是/app，那么访问路径应为/app/v3/api-docs）

5. 验证依赖兼容性 #

确认pom.xml（或build.gradle）中仅引入正确的springdoc依赖，无版本冲突：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.6.0</version>
</dependency>

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