从 OpenAPI 3.0 规范生成 TypeScript…

当需要把 OpenAPI 3.0 的 JSON/YAML 规范转换为 TypeScript 类型定义时使用。

适用场景

解决思路

1. 向用户索取 OpenAPI 文件路径（若未提供）。
2. 读取并校验文件，必须为 OpenAPI 3.0.x。
3. 从 components/schemas 中提取所有 schema。
4. 从 paths 中提取各端点的请求/响应类型。
5. 生成 TypeScript 代码（接口 + 类型守卫）。
6. 询问保存位置，默认保存到当前目录的 types/api.ts。
7. 写入文件。
8. 校验规范：检查 openapi 字段存在且以 3.0 开头、paths 字段存在、components.schemas 字段存在（若有类型）；若无效则报告错误并停止。
9. 类型映射-基础类型：string→string，number→number，integer→number，boolean→boolean，null→null。
10. 类型映射-格式修饰：uuid/date/date-time/email/uri 均映射为 string 并在注释中标注对应格式。
11. 类型映射-对象：properties 生成 interface，required[] 中的字段无 ?，其余字段带 ?。
12. 类型映射-数组：type: array 且 items 为某类型时生成该类型的数组（如 string[]）。
13. 类型映射-枚举：type: string 且 enum 列出值时生成字符串字面量联合类型（如 "active" | "draft"）。
14. 类型映射-oneOf：生成联合类型（如 Cat | Dog）。
15. 类型映射-allOf：生成继承/交叉（如 interface Extended extends Base）。
16. 生成文件头注释，包含来源文件、生成时间戳，并注明 DO NOT EDIT MANUALLY - Regenerate from OpenAPI schema。
17. 为 components/schemas 中每个 schema 生成 export interface，使用 OpenAPI 的 description 作为 JSDoc，required[] 内字段无 ?，其余带 ?。
18. 为 paths 中每个端点生成请求/响应类型，命名约定：{Method}{Path}Request 用于参数/请求体，{Method}{Path}Response 用于响应。
19. 为每个主要接口生成类型守卫函数：先检查 typeof value === 'object' && value !== null，对每个必填字段检查 'field' in value，基础类型字段检查 typeof，数组检查 Array.isArray()，枚举检查 .includes()。
20. 始终包含 ApiError 接口及其类型守卫 isApiError（检查 status 为 number、error 为 string）。
21. 处理 $ref：提取 schema 名称并直接引用该类型，不要内联展开（如 items: Product[]）。
22. 常见错误处理：OpenAPI 版本非 3.0.x 时报告仅支持 3.0；$ref 找不到时列出缺失的引用；未知类型使用 unknown 并警告；循环引用使用带惰性引用的类型别名。

适用边界 · 注意事项

• 输入不是 OpenAPI 3.0.x 规范（如 2.0 或 3.1）时不适用。
• 需要运行时校验而非静态类型时不适用（类型守卫仅做基础结构检查）。