Hey API Codegen

技能：openapi-ts

适用范围

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

前提条件

• @hey-api/openapi-ts v0+
• OpenAPI 3.0 规范格式
• TypeScript v5+，并启用 strict 模式
• 用于运行时验证的 Zod（使用 Zod 架构时）

原则

• 从 OpenAPI 规范生成客户端（单一事实来源）
• 使用生成的 Zod 架构进行运行时验证
• 客户端方法根据 OpenAPI 规范提供完整类型
• 错误响应根据 OpenAPI 错误架构提供类型
• 使用 createClient 工厂实例化客户端
• 在配置文件中设置输出格式和架构类型

约束

必须

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

应当

• 使用 Zod 架构（schemas.type: 'zod'）进行运行时验证
• 使用 Prettier 格式化（output.format: 'prettier'）
• 生成 TypeScript 枚举（types.enums: 'typescript'）

避免

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

交互

• 使用 fastify 生成的 OpenAPI 规范
• 与 nextjs 配合使用 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',
  },
  schemas: {
    type: 'zod',
  },
})

客户端使用模式

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 配合使用