Openapi To Typescript 说明文档

# OpenAPI to TypeScript 一个 Claude Code 技能，用于将 OpenAPI 3.0 规范（JSON 或 YAML）转换为 TypeScript 接口和类型守卫。 ## 目的 此技能自动化了从 OpenAPI API 规范生成类型安全 TypeScript 代码的过程。它创建： - 所有模式定义的 TypeScript 接口 - API 端点的请求/响应类型定义 - 用于验证的运行时类型守卫 - 对复杂类型（联合类型、交叉类型、枚举、数组）的正确处理 ## 何时使用 当您需要执行以下操作时使用此技能： - 从 OpenAPI 规范生成 TypeScript 类型 - 创建类型安全的 API 客户端接口 - 将 API 文档转换为 TypeScript 代码 - 维护后端 API 规范与前端代码之间的类型安全 ### 触发短语 - "generate types from openapi" - "convert openapi to typescript" - "create API interfaces" - "generate types from spec" - "convert schema to TS" ## 工作原理 ### 工作流 1. **请求输入**：询问 OpenAPI 文件路径（如果未提供） 2. **验证**：读取并验证 OpenAPI 规范（必须为 3.0.x） 3. **模式提取**：从 `components/schemas` 中提取模式 4. **端点分析**：从 `paths` 中提取请求/响应类型 5. **代码生成**：生成 TypeScript 接口和类型守卫 6. **输出**：询问保存位置（默认：`types/api.ts`） 7. **写入文件**：创建 TypeScript 文件 ### OpenAPI 支持 - **版本**：仅限 OpenAPI 3.0.x - **格式**：JSON 或 YAML - **必需字段**：`openapi`, `paths`, `components.schemas` ## 关键特性 ### 类型映射 **基本类型**： - `string` → `string` - `number` / `integer` → `number` - `boolean` → `boolean` - `null` → `null` **格式修饰符**（带有 JSDoc 注释）： - `uuid` → `string` (/** UUID */) - `date` → `string` (/** Date */) - `date-time` → `string` (/** ISO DateTime */) - `email` → `string` (/** Email */) - `uri` → `string` (/** URI */) **复杂类型**： - **对象** → 带有可选/必需字段的 TypeScript 接口 - **数组** → TypeScript 数组类型 (`Type[]`) - **枚举** → TypeScript 联合类型 (`"value1" | "value2"`) - **oneOf** → 联合类型 (`Type1 | Type2`) - **allOf** → 接口扩展 (`extends`) - **$ref** → 直接类型引用 ### 生成的代码结构 typescript /** * Auto-generated from: {source_file} * Generated at: {timestamp} * * DO NOT EDIT MANUALLY - Regenerate from OpenAPI schema */ // Types export interface User { ... } exp