🎁 Get the FREE AI Skills Starter Guide — Subscribe →
BytesAgainBytesAgain
BytesAgain › Skills › Swagger2 To Openapi3
🦀 ClawHub

Swagger2 To Openapi3

by @wangteng85859

Use when migrating Java Spring Boot projects from Swagger 2 (Springfox) to OpenAPI 3.0 (SpringDoc), including annotation replacements, import updates, and ja...

Versionv1.0.0
Downloads549
#coding#api#legal
TERMINAL
clawhub install swagger2-to-openapi3

📖 About This Skill

name: swagger2-to-openapi3 description: Use when migrating Java Spring Boot projects from Swagger 2 (Springfox) to OpenAPI 3.0 (SpringDoc), including annotation replacements, import updates, and javax-to-jakarta migration. Triggers on mentions of Swagger upgrade, OpenAPI migration, springfox to springdoc, or API documentation migration.

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

    • 注解替换速查表

    | Swagger 2 | OpenAPI 3.0 | 说明 | |-----------|-------------|------| | @Api | @Tag | 类/接口标注 | | @ApiOperation | @Operation | 方法标注 | | @ApiParam | @Parameter | 参数标注 | | @ApiModel | @Schema | 模型类标注 | | @ApiModelProperty | @Schema | 模型属性标注 | | @ApiResponse | @ApiResponse | 响应标注（保留） | | @ApiResponses | @ApiResponses | 多响应标注（保留） | | @ApiImplicitParam | @Parameter | 隐式参数 | | @ApiImplicitParams | @Parameters | 多隐式参数 |

    核心替换规则

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

    详细替换对照表

    | 旧包 (Swagger 2) | 新包 (OpenAPI 3.0) | |-----------------|-------------------| | io.swagger.annotations.Api | io.swagger.v3.oas.annotations.tags.Tag | | io.swagger.annotations.ApiOperation | io.swagger.v3.oas.annotations.Operation | | io.swagger.annotations.ApiParam | io.swagger.v3.oas.annotations.Parameter | | io.swagger.annotations.ApiModel | io.swagger.v3.oas.annotations.media.Schema | | io.swagger.annotations.ApiModelProperty | io.swagger.v3.oas.annotations.media.Schema | | io.swagger.annotations.ApiResponse | io.swagger.v3.oas.annotations.responses.ApiResponse | | io.swagger.annotations.ApiResponses | io.swagger.v3.oas.annotations.responses.ApiResponses |

    javax → jakarta 包替换

    | 旧包 (javax) | 新包 (jakarta) | |-------------|---------------| | javax.annotation.Resource | jakarta.annotation.Resource | | javax.annotation.PostConstruct | jakarta.annotation.PostConstruct | | javax.persistence.* | jakarta.persistence.* | | javax.validation.* | jakarta.validation.* | | javax.servlet.* | jakarta.servlet.* |

    自动迁移脚本

    使用说明

    本 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 场景。

    ⚡ When to Use

    TriggerAction
    - 迁移 Swagger 2 → OpenAPI 3.0
    - 更换 springfox → springdoc
    - javax 包升级到 jakarta

    📋 Tips & Best Practices

    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. 清理并重新构建项目