Springdoc 升级引发的 ClassNotFoundException 解析

问题描述

当开发者将 springdoc-openapi-starter-webmvc-ui 依赖从 2.6.0 升级到 2.7.0 后，应用启动时抛出以下异常：

java.lang.ClassNotFoundException: 
org.springframework.web.servlet.resource.LiteWebJarsResourceResolver

环境配置：

• Spring Boot 版本：3.3.5
• Spring Framework 版本：6.1.14

完整错误堆栈会显示类加载失败，导致应用上下文初始化中断，常见于测试环境或应用启动阶段。

错误根源

核心原因

LiteWebJarsResourceResolver 类是 Spring Framework 6.2 引入的新特性：

• ✅ Spring 6.2+：包含该类
• ❌ Spring 6.1.x：缺失该类

springdoc 2.7.x 依赖该组件，因此与旧版 Spring Boot 3.3.x（对应 Spring 6.1.x）存在版本冲突。本质是版本兼容性问题。

解决方案

方案1：回退 Springdoc 版本（推荐快速修复）

<!-- pom.xml -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <!-- 保持与Spring Boot 3.3.x兼容的版本 -->
    <version>2.6.0</version> 
</dependency>

操作步骤

1. 打开 pom.xml 或 build.gradle
2. 将 springdoc 版本从 2.7.0 改为 2.6.0
3. 执行清理操作 mvn clean install 或 gradle clean build

方案2：升级 Spring Boot（适用于长期维护）

<!-- pom.xml -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <!-- 升级到兼容springdoc 2.7.x的版本 -->
    <version>3.4.0</version> 
</parent>

升级注意事项

1. 验证其他依赖是否兼容 Spring Boot 3.4.x
2. 执行全面回归测试
3. 检查不推荐 API 的迁移建议

版本兼容性对照表

官方兼容性矩阵已明确版本匹配关系：

Spring Framework	Spring Boot	Springdoc
6.1.15	3.3.x	2.6.x
6.2.0+	3.4.x	2.7.x/2.8.x

资料参考：Springdoc Official Compatibility Matrix

根本原因解析

springdoc 2.7.x 在初始化时调用 SwaggerConfig 类，其内部尝试加载 LiteWebJarsResourceResolver。由于该类的字节码在 Spring 6.1 中不存在，JVM 抛出 NoClassDefFoundError，导致条件装配失败：

Caused by: java.lang.ClassNotFoundException: 
org.springframework.web.servlet.resource.LiteWebJarsResourceResolver

结论

依据当前环境选择修复方案：

• 紧急修复 → 回退 springdoc 至 2.6.x
• 系统升级 → 将 Spring Boot 升至 3.4.x 并保持 springdoc 2.7.x
• 生产环境建议先使用方案1确保稳定性，再规划完整版本升级

版本兼容问题可通过官方文档中的版本矩阵提前规避，确保三方依赖与基础框架的匹配性。