Swagger 2 到 OpenAPI 3.0 迁移指南

Overview

本 Skill 提供从 Swagger 2 (Springfox) 迁移到 OpenAPI 3.0 (SpringDoc) 的完整指南，包括：

• 注解替换对照表
• 自动替换脚本
• 包名迁移（javax → jakarta）
• 常见问题和解决方案

When to Use

• 升级 Spring Boot 2.x → 3.x
• 迁移 Swagger 2 → OpenAPI 3.0
• 更换 springfox → springdoc
• javax 包升级到 jakarta

注解替换速查表

核心替换规则

1. 类级别注解

@Api → @Tag

// Before (Swagger 2)
@Api(tags = "用户管理")
public class UserController {}

// After (OpenAPI 3.0)
@Tag(name = "用户管理")
public class UserController {}

2. 方法级别注解

@ApiOperation → @Operation

// Before
@ApiOperation(value = "获取用户信息", notes = "根据ID获取用户详情")
public User getUser(@ApiParam("用户ID") Long id) {}

// After
@Operation(summary = "获取用户信息", description = "根据ID获取用户详情")
public User getUser(@Parameter(description = "用户ID") Long id) {}

Response 处理（复杂替换）

// Before
@ApiOperation(value = "查询用户", response = User.class)
public ResponseEntity<User> query() {}

// After
@Operation(
    summary = "查询用户",
    responses = {
        @ApiResponse(
            responseCode = "200",
            content = @Content(schema = @Schema(implementation = User.class))
        )
    }
)
public ResponseEntity<User> query() {}

3. 模型类注解

@ApiModel → @Schema

// Before
@ApiModel(value = "用户对象", description = "用户信息")
public class UserDTO {}

// After
@Schema(description = "用户对象")
public class UserDTO {}

@ApiModelProperty → @Schema

// Before
@ApiModelProperty(value = "用户名", required = true, example = "张三")
private String username;

// After
@Schema(description = "用户名", requiredMode = Schema.RequiredMode.REQUIRED, example = "张三")
private String username;

包名替换

Swagger 包替换

// 旧包 (Swagger 2)
import io.swagger.annotations.*;

// 新包 (OpenAPI 3.0)
import io.swagger.v3.oas.annotations.*;
import io.swagger.v3.oas.annotations.media.*;
import io.swagger.v3.oas.annotations.responses.*;
import io.swagger.v3.oas.annotations.parameters.*;

详细替换对照表

javax → jakarta 包替换

自动迁移脚本

使用说明

本 skill 提供自动化脚本帮助快速完成迁移：

# 1. 执行完整迁移（注解 + 包名）
python scripts/migrate_swagger_to_openapi.py --project-path /path/to/your/project

# 2. 仅迁移注解
python scripts/migrate_annotations.py --project-path /path/to/your/project

# 3. 仅迁移包名
python scripts/migrate_imports.py --project-path /path/to/your/project

手动迁移建议

对于复杂的迁移场景，建议分步进行：

1. 先备份项目
2. 全局替换包名（使用 IDE 的全局替换功能）
3. 逐个文件检查注解替换
4. 特别注意 Response 相关的复杂替换

常见问题

Q1: @Api 的 tags 属性如何转换？

A: tags → name，多标签使用多个 @Tag 注解

// Before
@Api(tags = {"用户管理", "账号管理"})

// After
@Tag(name = "用户管理")
@Tag(name = "账号管理")

Q2: @ApiOperation 的 value 和 notes 如何对应？

A: value → summary，notes → description

// Before
@ApiOperation(value = "获取用户", notes = "详细说明...")

// After
@Operation(summary = "获取用户", description = "详细说明...")

Q3: response 属性最复杂，如何处理？

A: 需要使用 @ApiResponse + @Content + @Schema 组合

// Before
@ApiOperation(value = "查询", response = User.class)

// After
@Operation(
    summary = "查询",
    responses = {
        @ApiResponse(
            responseCode = "200",
            content = @Content(schema = @Schema(implementation = User.class))
        )
    }
)

Q4: 升级后 Swagger UI 无法访问？

A: 检查以下配置：

1. 添加 springdoc-openapi-starter-webmvc-ui 依赖
2. 配置 springdoc.api-docs.enabled=true
3. 访问地址从 /swagger-ui.html 变为 /swagger-ui/index.html

Q5: javax 包找不到？

A: Spring Boot 3.x 已迁移到 Jakarta EE，需要：

1. 将所有 javax. 替换为 jakarta.
2. 更新 pom.xml 中的依赖版本
3. 清理并重新构建项目

总结

迁移要点：

1. 注解层面：@Api→@Tag, @ApiOperation→@Operation, @ApiModel→@Schema
2. 包层面：swagger.annotations → swagger.v3.oas.annotations
3. JDK层面：javax. → jakarta.
4. 最复杂的是 Response 处理，需要组合多个注解

建议按文件逐个检查，特别注意复杂的 @ApiResponse 场景。