Swagger2 To Openapi3

SKILL.md

---
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**
```java
// Before (Swagger 2)
@Api(tags = "用户管理")
public class UserController {}

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

### 2. 方法级别注解

**@ApiOperation → @Operation**
```java
// 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 处理（复杂替换）**
```java
// 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**
```java
// Before
@ApiModel(value = "用户对象", description = "用户信息")
public class UserDTO {}

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

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

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

## 包名替换

### Swagger 包替换
```java
// 旧包 (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 提供自动化脚本帮助快速完成迁移：

```bash
# 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 注解
```java
// Before
@Api(tags = {"用户管理", "账号管理"})

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

### Q2: @ApiOperation 的 value 和 notes 如何对应？
**A:** `value` → `summary`，`notes` → `description`
```java
// Before
@ApiOperation(value = "获取用户", notes = "详细说明...")

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

### Q3: response 属性最复杂，如何处理？
**A:** 需要使用 @ApiResponse + @Content + @Schema 组合
```java
// 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 场景。