SpringBoot3集成Swagger时接口文档无法加载

Question

在SpringBoot 3集成Swagger时，接口文档无法加载的常见问题是因未正确适配SpringFox与SpringBoot 3的兼容性。SpringFox Swagger在SpringBoot 3中不再适用，因其底层依赖的Springfox-autoconfigure不支持Spring 6的反射机制和 Jakarta EE 包路径。即使成功启动项目，访问/swagger-ui.html也会返回404。正确方案是切换至`springdoc-openapi-starter-webmvc-ui`依赖，它原生支持Spring Boot 3和OpenAPI 3，并自动暴露`/swagger-ui/index.html`接口文档页面。需确保引入正确版本（如2.0+），并检查WebMvc配置是否拦截了相关路径。

Answer 1

SpringBoot 3 集成 Swagger 接口文档无法加载的深度解析与解决方案

1. 问题背景：从 SpringFox 到 Spring Boot 3 的兼容性断裂

在 Spring Boot 2.x 时代，springfox-swagger2 和 springfox-swagger-ui 是主流的 API 文档生成工具。开发者通过简单的注解配置即可实现自动化的接口文档展示。然而，随着 Spring Framework 6 和 Spring Boot 3 的发布，底层技术栈发生了根本性变化：

• Jakarta EE 取代了 Java EE，包路径由 javax.* 迁移至 jakarta.*
• Spring 6 引入了对 Jakarta EE 9+ 的全面支持
• 反射机制和类扫描逻辑发生变更，导致 SpringFox 的自动配置失效

由于 SpringFox 项目长期未更新，其核心模块 springfox-autoconfigure 无法适配上述变化，最终导致在 Spring Boot 3 环境中即使项目启动成功，访问 /swagger-ui.html 仍会返回 404 错误。

2. 根本原因分析：为何 SpringFox 不再适用？

我们可以通过依赖树来观察问题本质。执行以下命令查看依赖冲突：

mvn dependency:tree | grep springfox

常见输出如下：

依赖项	版本	兼容 Spring Boot 3?	问题描述
springfox-swagger2	2.9.2	❌	使用 javax.annotation，不支持 jakarta 包路径
springfox-swagger-ui	2.9.2	❌	静态资源映射失败，路径不可达
springfox-boot-starter	3.0.0	⚠️（部分）	虽支持 Boot 2.6，但未适配 Spring 6 反射增强

3. 正确技术选型：迁移到 springdoc-openapi

社区推荐的替代方案是 springdoc-openapi，它原生支持 OpenAPI 3 规范，并完全兼容 Spring Boot 3 与 Spring 6。其核心优势包括：

• 零配置启用 Swagger UI（默认路径：/swagger-ui/index.html）
• 基于 spring-boot-starter-webmvc 构建，无缝集成
• 支持 Jakarta EE 9+，无包路径冲突
• 提供丰富的扩展点（如 GroupedOpenApi、OpenApiCustomizer）

Maven 依赖配置示例如下：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.2</version>
</dependency>

4. 常见配置陷阱与排查流程

即便引入了正确的依赖，仍可能因 WebMvc 配置不当导致文档页面无法访问。以下是典型的排查流程图：

graph TD
            A[访问 /swagger-ui/index.html 返回 404] --> B{是否引入 springdoc-openapi-starter-webmvc-ui?}
            B -- 否 --> C[添加正确依赖并指定版本 >=2.0]
            B -- 是 --> D{是否存在自定义 WebMvcConfiguration?}
            D -- 是 --> E[检查 addResourceHandlers 是否拦截 /webjars/, /swagger-ui]
            D -- 否 --> F[检查 application.properties 中是否禁用 swagger]
            E --> G[确保 super.addResourceHandlers(registry)]
            F --> H[确认 springdoc.api-docs.path 和 swagger-ui.path 未被覆盖]
            G --> I[重启应用验证]
            H --> I

5. 实际案例：修复因 ResourceHandler 拦截导致的 404

某项目中存在如下 WebMvc 配置：

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
    }
}

该配置会拦截所有静态资源请求，包括 /webjars/ 和 /swagger-ui 路径。正确做法是保留父类默认注册：

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/webjars/**")
            .addResourceLocations("/webjars/")
            .resourceChain(false);
    registry.addResourceHandler("/**")
            .addResourceLocations("classpath:/static/");
}

6. 高级配置：多组文档、安全控制与定制化

对于复杂系统，可使用 GroupedOpenApi 实现接口分组：

@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("public")
            .pathsToMatch("/api/public/**")
            .build();
}

@bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .components(new Components())
            .info(new Info().title("My API").version("1.0"));
}

此外，可通过 springdoc.swagger-ui.operationsSorter=method 控制排序方式，提升可读性。

7. 版本兼容矩阵与升级建议

为避免未来再次出现兼容性问题，建议参考官方兼容表：

Spring Boot Version	springdoc-openapi Version	Recommended?
3.0 - 3.3	2.0.0 - 2.3.0	✅ 最佳实践
2.7 - 2.7.18	1.6.14	✅ LTS 支持
2.6.x	1.6.0	⚠️ 需注意 JDK 兼容性
< 2.6	< 1.6	❌ 不推荐新项目使用