openapi-ts-v0

用途

openapi-ts-v0 技能用于从 OpenAPI 3.0 规范生成 TypeScript 客户端，基于 @hey-api/openapi-ts 工具。其核心目标是以 OpenAPI 规范作为单一事实来源，生成完全类型化的 API 客户端，使客户端方法、错误响应等均从规范中推导出类型。

该技能不涵盖编写 OpenAPI 规范，也不涵盖 API 服务端实现（服务端实现可参考 fastify）。

主要能力

• 从 OpenAPI 3.0 规范生成 TypeScript 客户端。
• 客户端方法根据 OpenAPI 规范完全类型化。
• 错误响应根据 OpenAPI 错误 schema 类型化。
• 提供 createClient 工厂用于客户端实例化。
• 可在配置文件中配置输出格式和 schema 类型。
• Zod schema 和生成的 React Query 插件为可选附加项。

使用方式

配置模式

使用 openapi-ts.config.ts 进行配置，示例：

// openapi-ts.config.ts
import { defineConfig } from '@hey-api/openapi-ts'

export default defineConfig({
  input: './openapi.json',
  output: {
    path: './src/gen',
    format: 'prettier',
  },
  types: {
    enums: 'typescript',
  },
})

客户端使用模式

import { createClient } from './gen/client'

const client = createClient({
  baseUrl: 'https://api.example.com',
})

const response = await client.GET('/users/{id}', {
  params: { path: { id: '123' } },
})

if (response.error) {
  // Handle typed error
  return
}

// response.data is typed from OpenAPI spec

约束

必须（MUST）：

• 使用 openapi-ts.config.ts 进行配置。
• 在代码中使用之前先生成客户端。
• 处理 response.error 以获得类型化的错误响应。

建议（SHOULD）：

• 使用 Prettier 格式化（output.format: 'prettier'）。
• 生成 TypeScript 枚举（types.enums: 'typescript'）。
• 针对生成的客户端手写 TanStack Query hooks。
• 仅在需要运行时验证时添加 Zod schema（schemas.type: 'zod'）。
• 仅当项目选择加入时添加生成的 React Query 插件。

避免（AVOID）：

• 手动编辑生成的代码。
• 在没有错误处理的情况下使用生成的客户端。
• 混合生成的客户端代码和手动编写的客户端代码。

适用场景

• 需要从 OpenAPI 3.0 规范生成类型安全 TypeScript 客户端的项目。
• 使用 TypeScript v5+ 且开启严格模式的项目。
• 与 fastify 生成的 OpenAPI 规范配合使用。
• 与 next 配合使用 API 客户端。
• 与 TanStack Query 集成（参见 React Query Integration）。

限制

• 假设使用 @hey-api/openapi-ts v0+。
• 假设使用 OpenAPI 3.0 规范格式。
• 假设使用 TypeScript v5+ 且开启严格模式。
• 默认输出仅为类型和客户端；React Query hooks 需在消费应用中手写。
• 不涵盖编写 OpenAPI 规范。
• 不涵盖 API 服务端实现。

参考

• React Query Integration - 将生成的客户端与 TanStack Query 配合使用。