openapi-ts-v0

技能：openapi-ts

适用范围

• 适用于：使用 @hey-api/openapi-ts 根据 OpenAPI 3.0 规范生成 TypeScript 客户端
• 不适用于：编写 OpenAPI 规范、实现 API 服务端（参见 fastify）

前提条件

• @hey-api/openapi-ts v0+
• OpenAPI 3.0 规范格式
• TypeScript v5+，启用严格模式
• 默认仅生成类型和客户端；React Query 钩子由使用方应用手动编写

原则

• 根据 OpenAPI 规范生成客户端（单一事实来源）
• 客户端方法完全根据 OpenAPI 规范进行类型化
• 错误响应根据 OpenAPI 错误架构进行类型化
• 使用 createClient 工厂实例化客户端
• 在配置文件中设置输出格式和架构类型
• Zod 架构和生成的 React Query 插件均为可选扩展

约束

必须

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

应当

• 使用 Prettier 格式化（output.format: 'prettier'）
• 生成 TypeScript 枚举（types.enums: 'typescript'）
• 基于生成的客户端手动编写 TanStack Query 钩子
• 仅在需要运行时验证时添加 Zod 架构（schemas.type: 'zod'）
• 仅在项目选择使用时添加生成的 React Query 插件

避免

• 手动编辑生成的代码
• 使用生成的客户端时不处理错误
• 混用生成的客户端代码和手动编写的客户端代码

协作关系

• 使用由 fastify 生成的 OpenAPI 规范
• 与 next 配合，用于 API 客户端调用
• 集成 TanStack Query（参见 React Query 集成）

模式

配置模式

// 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

完整示例请参见 配置模板。

参考资料

• React Query 集成 - 使用生成的客户端与 TanStack Query