OpenApi规范在IntelliJ正常运行但Jar包启动失败求助

核心原因分析 #

IntelliJ运行正常但Jar包报错java.lang.NoClassDefFoundError: io/swagger/v3/oas/models/OpenAPI，通常是这几个情况：

• 依赖版本不兼容：SpringBoot 3.x对OpenAPI的支持需要适配的SpringDoc版本，单独引入swagger-models可能版本不对
• 依赖未被正确打包：Maven/Gradle打包配置有问题，导致依赖没被包含进可执行Jar
• 依赖冲突：项目中存在重复的swagger相关依赖，打包时被排除

具体解决步骤 #

1. 替换为适配SpringBoot3.x的OpenAPI依赖 #

SpringBoot3.x不再直接支持老的Swagger2，推荐使用SpringDoc OpenAPI，它已经内置了正确版本的swagger-models等依赖。直接在pom.xml中添加：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version> <!-- 版本号可根据SpringBoot3.x具体版本调整，比如2.2.0适配SpringBoot3.2+ -->
</dependency>

如果之前单独加了swagger-models，可以先移除，避免版本冲突。

2. 检查Maven打包插件配置 #

确保spring-boot-maven-plugin配置正确，尤其是repackage目标必须执行，这样才能把所有依赖打包进可执行Jar：

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <executions>
                <execution>
                    <goals>
                        <goal>repackage</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

3. 清理本地依赖缓存并重新构建 #

有时候本地Maven仓库的依赖缓存损坏，执行以下命令清理后重新构建：

mvn clean install -U

4. 排查依赖冲突 #

如果还是有问题，用Maven命令查看依赖树，检查是否有重复或版本不匹配的swagger相关依赖：

mvn dependency:tree | grep swagger

如果发现冲突，在对应依赖中排除掉旧版本的swagger-models或swagger-core：

<dependency>
    <!-- 你的某个依赖 -->
    <groupId>xxx</groupId>
    <artifactId>xxx</artifactId>
    <exclusions>
        <exclusion>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>
</dependency>

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