先校验 OpenAPI 文档并限定生成范围，再让 Claude 分层产出类型、请求函数与错误模型，最后通过模拟响应和类型检查验证客户端。
本教程的结果不是一整套自动生成平台，而是针对一份小型 OpenAPI 文档，得到可读、可测试的 TypeScript 客户端：路径和查询参数有类型，成功响应被解析，非成功状态统一转成明确错误，并通过模拟响应验证请求细节。
版本、权限与输入前提
本文面向 Claude 当前网页版或 Anthropic API 当前稳定接口，日期为 2026 年 8 月 30 日。模型名称、文件上下文限制、项目功能和代码生成工作流可能随账户变化，应先核对 Anthropic 官方文档与当前界面。本文不假定某个固定按钮、套餐或上下文容量。
| 前提 | 要求 |
|---|---|
| 规范文件 | 通过校验的 OpenAPI 3.x 文档，先选择少量路径 |
| 本地环境 | 已安装 Node.js、TypeScript 和项目测试工具 |
| 网络实现 | 明确使用原生 fetch、项目封装或其他已批准依赖 |
| 测试范围 | 能够模拟成功、客户端错误和服务端错误响应 |
不要从未经校验的 YAML 或 JSON 直接生成代码。先确认 operationId、参数位置、必填标记、响应状态和组件引用完整；含真实服务器地址、令牌示例或内部描述的文档应先脱敏。
先读规范，不要直接要求生成全部文件
OpenAPI 文档描述路径、操作、参数、请求体和响应等结构，具体定义应以 OpenAPI Specification 最新规范页为准。先让 Claude 输出端点清单和不确定项，检查规范本身是否存在同一响应多种结构、缺少错误体或 operationId 重复等问题。
请分析附带的 OpenAPI 3.x 文档，只处理指定的三个 operationId。
先输出：端点、HTTP 方法、路径参数、查询参数、请求体、成功响应、错误响应。
列出所有缺失或歧义，不要自行补造字段。
技术约束：TypeScript strict，使用项目现有 fetch 封装，不增加依赖。如果 Claude 根据接口名称猜出分页字段、认证头或错误格式，应删除这些推断并要求回到规范证据。规范没有描述的运行时行为，应标为待后端确认，而不是藏进生成代码。
规划客户端的最小结构
小型客户端可以分成四层：由 Schema 映射的类型、统一请求函数、每个 operation 的薄封装、用于非成功状态的错误类型。TypeScript 的联合类型、可选属性和类型收窄基础可参考 TypeScript Everyday Types。不要用 any 绕过规范中的不确定性。
| 层 | 职责 |
|---|---|
| types | 请求、响应、枚举和可复用 Schema 类型 |
| request | 基地址、请求头、序列化、状态判断和 JSON 解析 |
| operations | 组装路径、查询参数和请求体 |
| errors | 保留状态码、可解析错误体及原始响应信息 |
先让 Claude 生成类型文件，运行类型检查并人工对照 required、nullable、oneOf 和枚举。确认后再生成请求层。一次产出全部文件虽然更快，但引用错误和命名漂移更难定位。
分批生成 TypeScript 请求封装
- 生成公共类型。要求每个接口类型注明对应 operationId 或组件名称，保留可选字段语义。
- 实现统一请求函数。约定何时添加 Content-Type、如何处理无响应体状态，以及非 JSON 响应如何报告。
- 生成一个端点。先选择参数简单的 GET 操作，检查路径编码和查询参数是否忽略 undefined。
- 补请求体端点。验证方法、请求头和 JSON 序列化，不要在客户端补规范未要求的默认值。
- 复制已验证模式。其余端点逐个生成，每次运行类型检查与测试。
export class ApiError<T = unknown> extends Error {
constructor(
message: string,
public readonly status: number,
public readonly body: T
) { super(message) }
}这段结构只是错误模型示意，是否需要泛型、响应头或请求标识，应由项目要求决定。客户端中的类型不能验证真实网络数据；如果服务端可能偏离规范，还需要在运行时加入经过批准的验证方案。
用模拟响应验证参数与错误
- 成功响应：检查 URL、方法、请求头、请求体及返回对象。
- 路径参数：测试空格、斜杠或 Unicode 是否经过正确编码。
- 可选查询参数：undefined 不应变成字符串，零和 false 不应被错误省略。
- 客户端错误：模拟规范中定义的非成功状态，检查状态码与错误体。
- 异常响应：模拟空响应体或非 JSON 内容，确认错误处理不会覆盖原始状态。
测试应拦截网络层，不连接真实生产服务。除运行单元测试外，还要执行 TypeScript 类型检查，并查看生成文件的 Git 差异。若项目启用了格式化和 lint，单独运行它们，避免 Claude 为修复风格而改动无关模块。
失败诊断与人工复核
| 问题 | 优先检查 |
|---|---|
| 类型大量变成 unknown | 规范引用、组合 Schema 和生成提示中的保守策略 |
| 可选字段被当成必填 | required 数组，而不是只看 properties 是否存在 |
| URL 不正确 | 路径参数编码、基地址拼接和查询参数序列化 |
| 错误响应被当成成功 | 状态判断顺序及无响应体处理 |
| 测试通过但真实契约不符 | 模拟样本是否直接来自规范，而非照着实现编写 |
人工复核还要确认认证信息没有硬编码、日志不记录令牌、错误对象不会泄露敏感响应体。API 文档、示例和生成代码可能受到组织版权与许可约束；外发规范前应获得授权。Claude 网页或 API 的使用成本和额度按当前账户计算，不能从本文推断固定价格。
结论
Claude OpenAPI TypeScript 客户端生成应从小范围、已校验的规范开始：先提取事实，再生成类型、请求层和单个操作，最后用模拟响应和类型检查验证。Claude 可以减少机械编码，但规范歧义、兼容策略和安全边界仍必须由开发者决定。
常见问题
可以把完整 OpenAPI 文档一次交给 Claude 吗？
可以视上下文权限尝试，但更稳妥的是先选少量 operationId。分批处理便于发现引用、命名和错误响应中的歧义。
有 TypeScript 类型后还需要运行时验证吗？
视风险而定。TypeScript 只在开发和编译阶段提供约束，不能保证网络返回数据符合规范；外部或不稳定 API 更需要运行时检查。
生成客户端时应该使用 any 吗？
通常不应把 any 当作默认退路。规范不明确时可暂用 unknown，并在解析或类型收窄处显式处理，同时推动规范补全。