用途:从 OpenAPI 3.0 规范生成 TypeScript 客户端,让 API 规范成为唯一来源,避免手写客户端。
主要能力:由规范生成完全类型化的客户端方法;错误响应也按规范中的错误 schema 进行类型化;可通过 schemas.type: 'zod' 生成 Zod schema 用于运行时校验;可生成 TypeScript 枚举;用 createClient 工厂实例化客户端。
使用方式:在 openapi-ts.config.ts 中配置,通过 defineConfig 指定 input(如 ./openapi.json)、output.path 与 format、types.enums、schemas.type。生成后在代码中导入 createClient,传入 baseUrl,调用 client.GET('/users/{id}', { params: { path: { id: '123' } } }),并处理 response.error;成功后 response.data 按规范类型化。使用前必须先执行生成。
适用场景:TypeScript v5+ 严格模式项目,需要从 OpenAPI 规范产出类型安全客户端,可在 nextjs 等框架中配合使用,并可与 TanStack Query 集成。
限制与约束:仅覆盖从 OpenAPI 3.0 规范生成客户端,不涉及编写 OpenAPI 规范或 API 服务端实现;假设使用 @hey-api/openapi-ts v0+ 与 TypeScript v5+ 严格模式,Zod 仅在选用 Zod schema 时涉及;应避免手动修改生成代码、混用生成与手写客户端代码、以及在无错误处理时使用生成的客户端。具体安装命令、版本细节与完整配置示例在给定资料中暂未提供。