SpringBoot 2.x 升级到 3.x 时 Swagger 迁移完整指南

1. SpringBoot 2.x 到 3.x 的核心技术变更

基础依赖升级

• JDK版本要求：SpringBoot 3.x 要求最低 JDK 17，使用了 Record、Sealed Classes 等 Java 17 新特性
• Spring Framework 升级：从 5.x 升级到 6.x 版本
• Jakarta EE 迁移：包名从 javax.* 迁移到 jakarta.，如 javax.servlet. 变为 jakarta.servlet.*
• Netty 升级：SpringBoot 3.x 使用 Netty 5.x 版本

构建工具要求

• Maven 3.8.6+：推荐使用最新版本确保兼容性
• Gradle 7.6+：如果使用 Gradle 构建

2. Swagger 到 OpenAPI 3.0 的迁移变化

核心变更

SpringBoot 3.x 已完全转向 Jakarta EE 9+，不再支持 Swagger 2.0，转而采用 OpenAPI 3.0 规范。SpringFox（Swagger 2.x 的实现）已不再维护，官方推荐使用 SpringDoc OpenAPI 作为替代方案。

依赖库变更

• 移除的依赖：

  <!-- SpringBoot 2.x 中的 Swagger 依赖 -->
  <dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId>
  </dependency>
  <dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId>
  </dependency>
  

• 新引入的依赖：

  <!-- SpringBoot 3.x 中的 SpringDoc OpenAPI 依赖 -->
  <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  </dependency>
  

3. Maven 依赖配置变更

SpringBoot 2.x 与 3.x 依赖对比

SpringBoot 2.x (使用 Swagger 2.x)

<parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.7.10</version>
</parent><dependencies><!-- SpringBoot 基础依赖 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- Swagger 2.x 依赖 --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>3.0.0</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>3.0.0</version></dependency>
</dependencies>

SpringBoot 3.x (使用 SpringDoc OpenAPI 3.0)

<parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.2.6</version>
</parent><dependencies><!-- SpringBoot 基础依赖 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- SpringDoc OpenAPI 3.0 依赖 --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.5.0</version></dependency>
</dependencies>

4. 注解的变更

Swagger 2.x 与 OpenAPI 3.0 注解对照表

Swagger 2.x 注解 (io.swagger.annotations)	OpenAPI 3.0 注解 (io.swagger.v3.oas.annotations)	说明
@Api	@Tag	用于标记控制器类
@ApiModelProperty	@Schema	用于标记实体类属性
@ApiOperation	@Operation	用于标记接口方法
@ApiParam	@Parameter	用于标记接口参数
@ApiModel	@Schema	用于标记实体类
@ApiIgnore	@Hidden 或 @Operation(hidden = true)	用于忽略接口或属性

代码示例对比

Swagger 2.x 写法

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;@Api(value = "用户控制器", description = "用户相关接口")
public class UserController {@ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")public User getUser(@ApiParam(value = "用户ID", required = true) String userId) {// 方法实现}
}@ApiModel(description = "用户信息实体")
class User {@ApiModelProperty(value = "用户ID", required = true)private String userId;@ApiModelProperty(value = "用户名", required = true)private String username;// Getter 和 Setter 方法
}

OpenAPI 3.0 写法

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.License;
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Schema;@Tag(name = "用户控制器", description = "用户相关接口")
public class UserController {@Operation(summary = "获取用户信息", description = "根据用户ID获取用户信息")public User getUser(@Parameter(name = "userId", description = "用户ID", required = true) String userId) {// 方法实现}
}@Schema(description = "用户信息实体")
class User {@Schema(name = "userId", description = "用户ID", required = true)private String userId;@Schema(name = "username", description = "用户名", required = true)private String username;// Getter 和 Setter 方法
}

5. 配置类的迁移方法

SpringBoot 2.x Swagger 配置

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.gradle.plugins.SwaggerGradlePlugin;@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build();}
}

SpringBoot 3.x SpringDoc 配置

import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class SpringDocConfig {@Beanpublic GroupedOpenApi publicApi() {return GroupedOpenApi.builder().group("public-api").packagesToScan("com.example.demo.controller").build();}
}

6. 代码迁移的具体步骤

第一步：更新项目依赖

1. 升级 JDK 到 17 或更高版本
2. 更新 SpringBoot 版本到 3.x 系列
3. 移除 Swagger 2.x 依赖，添加 SpringDoc OpenAPI 依赖

第二步：替换包名

将代码中所有 javax.* 包名替换为 jakarta.* 包名：

• javax.servlet.* → jakarta.servlet.*
• javax.persistence.* → jakarta.persistence.*
• 等其他相关包名

第三步：迁移注解

按照注解对照表将 Swagger 2.x 注解替换为 OpenAPI 3.0 注解

• @Api → @Tag
• @ApiOperation → @Operation
• @ApiParam → @Parameter
• @ApiModel → @Schema
• @ApiModelProperty → @Schema

第四步：配置调整

1. 更新配置类，从 Swagger 2.x 配置迁移到 SpringDoc 配置
2. 调整 application.yml/properties 配置
3. 确保拦截器排除新的 Swagger 路径

7. 常见升级问题和解决方案

问题1：包名冲突

解决方案：全局替换包名，使用 IDE 的全局搜索替换功能：

// 需要替换的包名
javax.servlet.http.HttpServletRequest → jakarta.servlet.http.HttpServletRequest
javax.persistence.Entity → jakarta.persistence.Entity

问题2：依赖兼容性

解决方案：确保所有第三方依赖都兼容 SpringBoot 3.x 和 Java 17

问题3：注解不识别

解决方案：导入正确的包：

// 导入新包
import io.swagger.v3.oas.annotations.Tag;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;

问题4：接口文档不显示

解决方案：检查配置是否正确，确保：

1. 依赖已正确添加
2. 注解已正确替换
3. 拦截器未拦截 Swagger 路径

8. 新版本的特性优势和最佳实践

SpringDoc OpenAPI 优势

• 完全支持 OpenAPI 3.0 规范
• 更简洁的注解语法
• 更好的代码推断能力
• 支持 Markdown 格式的接口描述
• 更丰富的自定义选项

最佳实践建议

1. 使用分组功能：将 API 分组管理
2. 启用接口扫描过滤：只扫描需要文档化的接口
3. 自定义接口信息：设置统一的接口描述信息
4. 环境控制：在不同环境中启用/禁用 Swagger
5. 集成安全认证：在生产环境中对 Swagger 进行安全限制

9. 配置示例

application.yml 配置

springdoc:api-docs:enabled: truepath: /v3/api-docsswagger-ui:enabled: truepath: /swagger-ui.htmlopenapi:info:title: 'SpringBoot 3.x API 文档'description: '这是一个使用 SpringDoc OpenAPI 3.0 的 API 文档示例'version: '1.0.0'contact:name: '开发者'url: 'https://example.com'email: '[e-mail]'

完整的 SpringDocConfig 配置类

import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;@Configuration
public class SpringDocConfig {@Beanpublic GroupedOpenApi publicApi() {return GroupedOpenApi.builder().group("public-api").packagesToScan("com.example.demo.controller").build();}@Beanpublic OpenAPI springShopOpenAPI() {return new OpenAPI().info(new Info().title("SpringBoot 3.x API 文档").description("这是一个使用 SpringDoc OpenAPI 3.0 的 API 文档示例").version("1.0.0").contact(new Contact().name("开发者").url("https://example.com").email("[e-mail]")).license(new License().name("Apache 2.0").url("https://www.apache.org/licenses/LICENSE-2.0")));}
}