# OpenAPI Generator v2 使用文档

## 概述

`gen-api-v2` 是一个全新设计的 OpenAPI/Swagger 代码生成器，支持完整的 OpenAPI 2.x (Swagger) 和 3.x 标准。相比原版生成器，v2 版本具有更好的稳定性、可扩展性和错误处理能力。

## 主要特性

### ✅ 完整标准支持
- **OpenAPI 3.x**: 完全支持最新的 OpenAPI 3.0/3.1 规范
- **Swagger 2.x**: 向下兼容 Swagger 2.0 规范
- **自动检测**: 自动识别文档版本并使用相应的解析逻辑

### ✅ 增强的类型系统
- **精确类型映射**: 支持所有 JSON Schema 类型
- **联合类型**: 支持 `oneOf`、`anyOf`、`allOf` 组合
- **枚举类型**: 支持标准枚举和扩展枚举注释
- **内联对象**: 支持复杂的嵌套对象类型
- **泛型支持**: 更好的 TypeScript 泛型推导

### ✅ 稳定的架构设计
- **模块化设计**: 清晰的职责分离，易于维护和扩展
- **错误恢复**: 单个接口解析失败不影响整体生成
- **缓存机制**: 类型解析缓存，提高生成效率
- **依赖管理**: 智能的类型依赖分析和排序

### ✅ 增强的错误处理
- **详细错误信息**: 精确定位问题所在的接口和字段
- **优雅降级**: 遇到不支持的特性时使用 `any` 类型而非崩溃
- **进度反馈**: 清晰的生成进度和结果统计

## 安装使用

### 全局安装
```bash
npm install -g @rockyf/easy-api
```

### 项目内安装
```bash
npm install @rockyf/easy-api
npx gen-api-v2 --help
```

## 命令行参数

| 参数 | 简写 | 类型 | 默认值 | 说明 |
|------|------|------|--------|------|
| `--input` | `-i` | string | - | **必需** OpenAPI 文档 URL 或文件路径 |
| `--output` | `-o` | string | `.` | 输出目录 |
| `--root-path` | `-r` | string | `''` | API 根路径前缀 |
| `--namespace` | `-n` | string | `api` | TypeScript 命名空间 |
| `--headers` | `-h` | string[] | - | HTTP 请求头（用于获取文档） |
| `--method` | `-m` | string | `get` | HTTP 请求方法 |
| `--data-field` | `-d` | string | `data` | 响应数据字段名 |
| `--not-code-data-mode` | - | boolean | false | 禁用 code-data 响应模式 |
| `--vite` | - | boolean | false | 生成 Vite 兼容的导入 |

## 使用示例

### 基础使用
```bash
# 从在线文档生成
gen-api-v2 -i "https://api.example.com/swagger.json" -o "src/api" -n "myApi"

# 从本地文件生成
gen-api-v2 -i "./swagger.json" -o "src/api" -n "myApi"
```

### 带认证的API文档
```bash
gen-api-v2 \
  -i "https://api.example.com/swagger.json" \
  -o "src/api" \
  -n "myApi" \
  -h "Authorization: Bearer your-token" \
  -h "X-API-Key: your-api-key"
```

### 指定API根路径
```bash
gen-api-v2 \
  -i "https://api.example.com/swagger.json" \
  -o "src/api" \
  -n "myApi" \
  -r "/api/v1"
```

### Vite项目使用
```bash
gen-api-v2 \
  -i "https://api.example.com/swagger.json" \
  -o "src/api" \
  -n "myApi" \
  --vite
```

## 生成的文件结构

执行命令后会生成两个文件：

```
src/api/
├── myApi-types.ts      # TypeScript 类型定义
└── myApi-configs.json  # API 配置文件
```

### 类型定义文件 (`myApi-types.ts`)
```typescript
import { CallApiOptions, EasyApiFunc } from "@rockyf/easy-api"

export declare namespace myApi {
    // 数据模型接口
    interface User {
        id: number
        name: string
        email?: string
    }
    
    interface CreateUserRequest {
        name: string
        email: string
    }
    
    // API 接口定义
    type IApis = {
        user: {
            /**获取用户列表*/
            getList: ((params?: any, options?: CallApiOptions) => Promise<User[]>) & EasyApiFunc
            /**创建用户*/
            postCreate: ((params: CreateUserRequest, options?: CallApiOptions) => Promise<User>) & EasyApiFunc
            /**获取用户详情*/
            getById: ((id: User['id'], params?: any, options?: CallApiOptions) => Promise<User>) & EasyApiFunc
        }
    }
}
```

### 配置文件 (`myApi-configs.json`)
```json
{
    "path": "/api/v1",
    "user": {
        "path": "/user",
        "getList": {
            "method": "GET"
        },
        "postCreate": {
            "method": "POST"
        },
        "getById": {
            "method": "GET",
            "path": "/{id}"
        }
    }
}
```

## 在项目中使用

### 1. 创建 API 实例
```typescript
import { buildApiCollection } from '@rockyf/easy-api'
import apiConfigs from './myApi-configs.json'
import type { myApi } from './myApi-types'

export const api = buildApiCollection<myApi.IApis>(apiConfigs)
```

### 2. 调用 API
```typescript
import { api } from './api'

// 获取用户列表
const users = await api.user.getList()

// 创建用户
const newUser = await api.user.postCreate({
    name: 'John Doe',
    email: 'john@example.com'
})

// 获取用户详情
const user = await api.user.getById(123)
```

## 高级特性

### 自定义配置
```typescript
import { buildApiCollection } from '@rockyf/easy-api'
import apiConfigs from './myApi-configs.json'
import type { myApi } from './myApi-types'

// 添加全局配置
export const api = buildApiCollection<myApi.IApis>(
    apiConfigs,
    {}, // 现有API对象
    {
        // 全局请求配置
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer ' + getToken()
        },
        // 全局插件
        plugins: [apiLogger({ beauty: true })]
    }
)
```

### 错误处理
```typescript
import { CodeError } from '@rockyf/easy-api'

try {
    const user = await api.user.getById(123)
    console.log(user)
} catch (error) {
    if (error instanceof CodeError) {
        console.error('API Error:', error.code, error.message)
    } else {
        console.error('Network Error:', error)
    }
}
```

## 与原版生成器的对比

| 特性 | 原版 gen-api | 新版 gen-api-v2 |
|------|-------------|----------------|
| OpenAPI 3.x 支持 | 部分 | ✅ 完整 |
| Swagger 2.x 支持 | ✅ | ✅ |
| 类型系统 | 基础 | ✅ 增强 |
| 错误处理 | 基础 | ✅ 完善 |
| 扩展性 | 有限 | ✅ 良好 |
| 稳定性 | 一般 | ✅ 优秀 |
| 性能 | 一般 | ✅ 优化 |

## 迁移指南

### 从原版生成器迁移

1. **替换命令**: 将 `gen-api` 替换为 `gen-api-v2`
2. **参数兼容**: 所有原有参数都兼容，可直接使用
3. **生成文件**: 文件格式完全兼容，无需修改使用代码
4. **增量升级**: 可以逐步替换，两个版本可以共存

### 示例迁移
```bash
# 原版命令
gen-api -i "https://api.example.com/swagger.json" -o "src/api" -n "myApi"

# 新版命令（直接替换）
gen-api-v2 -i "https://api.example.com/swagger.json" -o "src/api" -n "myApi"
```

## 故障排除

### 常见问题

1. **文档获取失败**
   ```
   ❌ Failed to fetch document: 401 Unauthorized
   ```
   解决：检查认证信息，使用 `-h` 参数添加必要的请求头

2. **类型生成失败**
   ```
   ❌ Error generating interface for UserSchema: Invalid schema
   ```
   解决：检查 OpenAPI 文档的 schema 定义是否符合规范

3. **路径解析错误**
   ```
   ⚠️ No APIs generated for root path: /api/v1
   ```
   解决：检查 `-r` 参数是否与文档中的路径匹配

### 调试技巧

1. **启用详细日志**: 生成器会输出详细的进度信息
2. **检查生成文件**: 查看生成的类型文件是否符合预期
3. **验证配置**: 检查生成的配置文件路径和方法是否正确

## 扩展开发

### 插件系统
生成器v2保持了与原有插件系统的完全兼容：

```typescript
import { apiLogger } from '@rockyf/easy-api'

// 使用内置插件
export const api = buildApiCollection<myApi.IApis>(apiConfigs, {}, {
    plugins: [apiLogger({ beauty: true })]
})
```

### 自定义插件
```typescript
import type { Plugin } from '@rockyf/easy-api'

const customPlugin: Plugin = {
    beforeCall(context) {
        console.log('调用API:', context.url)
    },
    afterCall(context) {
        console.log('API响应:', context.respObject)
    }
}
```

## 版本兼容性

- **Node.js**: >= 14.0.0
- **TypeScript**: >= 4.0.0
- **OpenAPI**: 2.0, 3.0.x, 3.1.x
- **Swagger**: 2.0

## 更新日志

### v2.0.0
- ✅ 全新架构设计
- ✅ 完整 OpenAPI 3.x 支持
- ✅ 增强的类型系统
- ✅ 改进的错误处理
- ✅ 更好的扩展性

---

如有问题或建议，请提交 Issue 或 Pull Request。