Java 21+Spring Boot 3.2.0-SNAPSHOT下Swagger UI空白无API问题求助

针对Java 21 + Spring Boot 3.2.0-SNAPSHOT + springdoc-openapi-starter-webmvc-ui 2.2.0环境下Swagger UI空白、未加载API接口的问题，可按以下步骤逐一排查：

1. 版本兼容性校验 #

Spring Boot 3.2.0-SNAPSHOT为快照版本，可能与springdoc 2.2.0存在兼容性适配问题：

• 优先建议切换至Spring Boot 3.1.x稳定版本搭配springdoc 2.2.0；
• 若需保留快照版Spring Boot，可尝试升级springdoc至最新快照版本（如2.3.0-SNAPSHOT），确保依赖版本匹配。

2. 核心配置检查 #

2.1 配置文件（application.properties/yaml） #

确保添加以下关键配置，指定API文档生成规则：

# 启用API文档生成
springdoc.api-docs.enabled=true
# 启用Swagger UI
springdoc.swagger-ui.enabled=true
# 指定控制器扫描包路径（替换为你的实际包名）
springdoc.packages-to-scan=com.yourpackage.controller
# 自定义Swagger UI访问路径
springdoc.swagger-ui.path=/swagger-ui.html

2.2 新增OpenAPI配置类 #

创建配置类明确API文档元信息，确保Spring能识别并加载：

@Configuration
@OpenAPIDefinition(
    info = @Info(
        title = "Person管理API",
        version = "v1",
        description = "Person相关接口文档"
    )
)
public class OpenApiConfig {
}

3. 控制器注解规范 #

检查PersonController的注解是否符合要求：

• 类上必须标注@RestController或@Controller；
• 接口方法需使用@GetMapping/@PostMapping等Spring MVC请求注解；
• 可添加OpenAPI注解增强文档可读性（非强制，但能确保接口被识别）：

@RestController
@RequestMapping("/api/persons")
public class PersonController {

    @GetMapping
    @Operation(summary = "获取所有Person列表", description = "返回系统中所有Person数据")
    public List<Person> listAllPersons() {
        // 业务逻辑
        return new ArrayList<>();
    }
}

4. 静态资源与权限放行 #

4.1 静态资源拦截排查 #

若自定义了WebMvcConfigurer，需确保放行Swagger相关静态资源路径：

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

4.2 Spring Security权限放行 #

若项目集成了Spring Security，需在配置类中放行Swagger相关接口：

@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(auth -> auth
                // 放行Swagger相关路径
                .requestMatchers("/swagger-ui/**", "/v3/api-docs/**", "/v3/api-docs.yaml").permitAll()
                // 其他接口按需配置权限
                .anyRequest().authenticated());
        return http.build();
    }
}

5. 后端API文档验证 #

先访问http://localhost:8080/v3/api-docs（端口替换为你的项目端口）：

• 若返回JSON格式的API文档内容，说明后端生成正常，问题出在Swagger UI加载环节，重点排查静态资源或路径配置；
• 若返回404或空内容，说明后端未生成API文档，需检查控制器扫描、注解配置或依赖冲突。

6. 依赖冲突排查 #

检查项目依赖中是否存在旧版Swagger相关依赖（如springfox-swagger2），此类依赖会与springdoc冲突，需彻底移除。

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