升级SpringDoc 2.8.0后启动失败：无法自省SwaggerConfig类

问题重现 #

升级springdoc-openapi-starter-webmvc-ui至2.8.0后，应用启动报错：

Caused by: java.lang.IllegalStateException: Failed to introspect Class [org.springdoc.webmvc.ui.SwaggerConfig] 
from ClassLoader [org.springframework.boot.loader.launch.LaunchedClassLoader]

常见解决方案 #

• 检查Spring Boot版本兼容性
  SpringDoc 2.x系列（含2.8.0）仅支持Spring Boot 3.x及以上版本。若你的应用仍使用Spring Boot 2.x，有两种选择：

  • 降级SpringDoc到1.x稳定版（如1.6.14），适配Spring Boot 2.x；
  • 升级Spring Boot到3.x版本，匹配SpringDoc 2.8.0的要求。

• 清理依赖冲突

  • 移除pom.xml中所有旧的SpringDoc相关依赖（如springdoc-openapi-ui、springdoc-openapi-webmvc-core等1.x版本依赖），仅保留springdoc-openapi-starter-webmvc-ui；
  • 执行mvn dependency:tree查看依赖树，排查是否存在swagger-core、swagger-models等旧版本冲突依赖，通过<exclusions>标签排除冲突项。

• 修复类加载与依赖缓存问题

  • 若使用Spring Boot Fat Jar打包，确保打包配置未排除SpringDoc相关类；
  • 删除本地Maven仓库中SpringDoc相关目录（~/.m2/repository/org/springdoc），执行mvn clean install重新下载依赖。

• 临时降级SpringDoc版本
  若暂时无法调整Spring Boot版本，可将SpringDoc版本降级至2.7.0，该版本兼容性更稳定，部分场景下可规避此反射报错。

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