Swagger2 To Openapi3

⚡ When to Use

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