名称: openapi-to-typescript 描述: 将OpenAPI 3.0 JSON/YAML转换为TypeScript接口和类型守卫。当用户要求从OpenAPI生成类型、将模式转换为TS、创建API接口或从API规范生成TypeScript类型时，应使用此技能。

OpenAPI 到 TypeScript

将OpenAPI 3.0规范转换为TypeScript接口和类型守卫。

输入: OpenAPI文件（JSON或YAML） 输出: TypeScript文件，包含接口和类型守卫

何时使用

“从openapi生成类型”
“将openapi转换为typescript”
“创建API接口”
“从规范生成类型”

工作流程

请求OpenAPI文件路径（如果未提供）
读取和验证文件（必须是OpenAPI 3.0.x）
从components/schemas提取模式
从paths提取端点（请求/响应类型）
生成TypeScript（接口 + 类型守卫）
询问保存位置（默认：当前目录下的types/api.ts）
写入文件

OpenAPI验证

处理前检查：

- 字段"openapi"必须存在并以"3.0"开头
- 字段"paths"必须存在
- 字段"components.schemas"必须存在（如果有类型）

如果无效，报告错误并停止。

类型映射

基本类型

OpenAPI	TypeScript
`string`	`string`
`number`	`number`
`integer`	`number`
`boolean`	`boolean`
`null`	`null`

格式修饰符

格式	TypeScript
`uuid`	`string` (注释 UUID)
`date`	`string` (注释日期)
`date-time`	`string` (注释 ISO)
`email`	`string` (注释邮箱)
`uri`	`string` (注释 URI)

复杂类型

对象:

// OpenAPI: type: object, properties: {id, name}, required: [id]
interface Example {
  id: string;      // required: 无 ?
  name?: string;   // optional: 带 ?
}

数组:

// OpenAPI: type: array, items: {type: string}
type Names = string[];

枚举:

// OpenAPI: type: string, enum: [active, draft]
type Status = "active" | "draft";

oneOf (联合):

// OpenAPI: oneOf: [{$ref: Cat}, {$ref: Dog}]
type Pet = Cat | Dog;

allOf (交集/扩展):

// OpenAPI: allOf: [{$ref: Base}, {type: object, properties: ...}]
interface Extended extends Base {
  extraField: string;
}

代码生成

文件头

/**
 * 自动生成自: {source_file}
 * 生成于: {timestamp}
 *
 * 请勿手动编辑 - 从OpenAPI模式重新生成
 */

接口（从components/schemas）

对于components/schemas中的每个模式：

export interface Product {
  /** 产品唯一标识符 */
  id: string;

  /** 产品标题 */
  title: string;

  /** 产品价格 */
  price: number;

  /** 创建时间戳 */
  created_at?: string;
}

使用OpenAPI描述作为JSDoc
required[]中的字段无?
required[]外的字段有?

请求/响应类型（从paths）

对于paths中的每个端点：

// GET /products - 查询参数
export interface GetProductsRequest {
  page?: number;
  limit?: number;
}

// GET /products - 响应 200
export type GetProductsResponse = ProductList;

// POST /products - 请求体
export interface CreateProductRequest {
  title: string;
  price: number;
}

// POST /products - 响应 201
export type CreateProductResponse = Product;

命名约定：

{Method}{Path}Request 用于参数/体
{Method}{Path}Response 用于响应

类型守卫

对于每个主要接口，生成一个类型守卫：

export function isProduct(value: unknown): value is Product {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    typeof (value as any).id === 'string' &&
    'title' in value &&
    typeof (value as any).title === 'string' &&
    'price' in value &&
    typeof (value as any).price === 'number'
  );
}

类型守卫规则：

检查 typeof value === 'object' && value !== null
对于每个必需字段：检查 'field' in value
对于基本类型字段：检查 typeof
对于数组：检查 Array.isArray()
对于枚举：检查 .includes()

错误类型（始终包含）

export interface ApiError {
  status: number;
  error: string;
  detail?: string;
}

export function isApiError(value: unknown): value is ApiError {
  return (
    typeof value === 'object' &&
    value !== null &&
    'status' in value &&
    typeof (value as any).status === 'number' &&
    'error' in value &&
    typeof (value as any).error === 'string'
  );
}

$ref 解析

当遇到 {"$ref": "#/components/schemas/Product"} 时：

提取模式名称 (Product)
直接使用类型（不要内联解析）

// OpenAPI: items: {$ref: "#/components/schemas/Product"}
// TypeScript:
items: Product[]  // 引用，非内联

完整示例

输入 (OpenAPI):

{
  "openapi": "3.0.0",
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": {"type": "string", "format": "uuid"},
          "email": {"type": "string", "format": "email"},
          "role": {"type": "string", "enum": ["admin", "user"]}
        },
        "required": ["id", "email", "role"]
      }
    }
  },
  "paths": {
    "/users/{id}": {
      "get": {
        "parameters": [{"name": "id", "in": "path", "required": true}],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/User"}
              }
            }
          }
        }
      }
    }
  }
}

输出 (TypeScript):

/**
 * 自动生成自: api.openapi.json
 * 生成于: 2025-01-15T10:30:00Z
 *
 * 请勿手动编辑 - 从OpenAPI模式重新生成
 */

// ============================================================================
// 类型
// ============================================================================

export type UserRole = "admin" | "user";

export interface User {
  /** UUID */
  id: string;

  /** 邮箱 */
  email: string;

  role: UserRole;
}

// ============================================================================
// 请求/响应类型
// ============================================================================

export interface GetUserByIdRequest {
  id: string;
}

export type GetUserByIdResponse = User;

// ============================================================================
// 类型守卫
// ============================================================================

export function isUser(value: unknown): value is User {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    typeof (value as any).id === 'string' &&
    'email' in value &&
    typeof (value as any).email === 'string' &&
    'role' in value &&
    ['admin', 'user'].includes((value as any).role)
  );
}

// ============================================================================
// 错误类型
// ============================================================================

export interface ApiError {
  status: number;
  error: string;
  detail?: string;
}

export function isApiError(value: unknown): value is ApiError {
  return (
    typeof value === 'object' &&
    value !== null &&
    'status' in value &&
    typeof (value as any).status === 'number' &&
    'error' in value &&
    typeof (value as any).error === 'string'
  );
}

常见错误

错误	操作
OpenAPI版本 != 3.0.x	报告只支持3.0
$ref 未找到	列出缺失的引用
未知类型	使用`unknown`并警告
循环引用	使用带延迟引用的类型别名