openapi-ts-v0

スキル：openapi-ts

適用範囲

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

前提条件

• @hey-api/openapi-ts v0 以降
• OpenAPI 3.0 仕様の形式
• strict モードの 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 仕様を使用します
• API クライアントの利用では next と連携します
• TanStack Query と連携します（React Query Integration を参照）

パターン

設定パターン

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

完全な例については、Config Template を参照してください。

参考資料

• React Query Integration - 生成されたクライアントを TanStack Query と使用する方法