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

文章目录

• • [1. SpringBoot 2.x 到 3.x 的核心技术变更](#1. SpringBoot 2.x 到 3.x 的核心技术变更)
  • • 基础依赖升级
    • 构建工具要求
  • [2. Swagger 到 OpenAPI 3.0 的迁移变化](#2. Swagger 到 OpenAPI 3.0 的迁移变化)
  • • 核心变更
    • 依赖库变更
  • [3. Maven 依赖配置变更](#3. Maven 依赖配置变更)
  • • [SpringBoot 2.x 与 3.x 依赖对比](#SpringBoot 2.x 与 3.x 依赖对比)
    • • [SpringBoot 2.x (使用 Swagger 2.x)](#SpringBoot 2.x (使用 Swagger 2.x))
      • [SpringBoot 3.x (使用 SpringDoc OpenAPI 3.0)](#SpringBoot 3.x (使用 SpringDoc OpenAPI 3.0))
  • [4. 注解的变更](#4. 注解的变更)
  • • [Swagger 2.x 与 OpenAPI 3.0 注解对照表](#Swagger 2.x 与 OpenAPI 3.0 注解对照表)
    • 代码示例对比
    • • [Swagger 2.x 写法](#Swagger 2.x 写法)
      • [OpenAPI 3.0 写法](#OpenAPI 3.0 写法)
  • [5. 配置类的迁移方法](#5. 配置类的迁移方法)
  • • [SpringBoot 2.x Swagger 配置](#SpringBoot 2.x Swagger 配置)
    • [SpringBoot 3.x SpringDoc 配置](#SpringBoot 3.x SpringDoc 配置)
  • [6. 代码迁移的具体步骤](#6. 代码迁移的具体步骤)
  • • 第一步：更新项目依赖
    • 第二步：替换包名
    • 第三步：迁移注解
    • 第四步：配置调整
  • [7. 常见升级问题和解决方案](#7. 常见升级问题和解决方案)
  • • 问题1：包名冲突
    • 问题2：依赖兼容性
    • 问题3：注解不识别
    • 问题4：接口文档不显示
  • [8. 新版本的特性优势和最佳实践](#8. 新版本的特性优势和最佳实践)
  • • [SpringDoc OpenAPI 优势](#SpringDoc OpenAPI 优势)
    • 最佳实践建议
  • [9. 配置示例](#9. 配置示例)
  • • [application.yml 配置](#application.yml 配置)
    • [完整的 SpringDocConfig 配置类](#完整的 SpringDocConfig 配置类)

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 {
    @Bean
    public 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 {
    @Bean
    public 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: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
  openapi:
    info:
      title: 'SpringBoot 3.x API 文档'
      description: '这是一个使用 SpringDoc OpenAPI 3.0 的 API 文档示例'
      version: '1.0.0'
      contact:
        name: '开发者'
        url: 'https://example.com'
        email: 'developer@example.com'

完整的 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 {

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public-api")
                .packagesToScan("com.example.demo.controller")
                .build();
    }

    @Bean
    public 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("developer@example.com"))
                        .license(new License()
                                .name("Apache 2.0")
                                .url("https://www.apache.org/licenses/LICENSE-2.0")));
    }
}