Hey API Codegen

スキル：openapi-ts

対象範囲

• 対象：@hey-api/openapi-ts を使用した OpenAPI 3.0 仕様からの TypeScript クライアントの生成
• 対象外：OpenAPI 仕様の作成、API サーバーの実装（fastify を参照）

前提条件

• @hey-api/openapi-ts v0+
• OpenAPI 3.0 仕様形式
• strict モードの TypeScript v5+
• 実行時検証用の 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 仕様を使用します
• API クライアントの使用において nextjs と連携します
• 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 とともに使用する方法