openapi-ts-client

openapi-ts-client — SKILL.md

バリアント： standard · 使用する場面： @hey-api/openapi-ts を使って OpenAPI 3.1 コントラクトから型付き TS クライアント／SDK を生成する場合。

概要

@hey-api/openapi-ts は、OpenAPI 用にメンテナンスされている TypeScript コードジェネレーターです。FastAPI 自身のドキュメントで TS クライアント向けに推奨されているツールです。OpenAPI 3.1 ドキュメント（稼働中の /openapi.json URL または保存済みファイル）を指定すると、型付きモデル、型付き SDK（操作ごとに非同期関数を 1 つ）、さらにプラグインを使って TanStack Query フックと Zod スキーマを生成します。生成されたクライアントはビルド成果物です。OpenAPI コントラクトを唯一の信頼できる情報源とし、手作業で編集するのではなく再生成します。このスキルでは、設定方法、クライアントのトランスポートの選択、TanStack Query と Zod のプラグインの有効化、再生成と差分チェックのワークフロー、FastAPI 固有の operationId 命名の修正について説明します。@hey-api/openapi-ts v0.98.2（0.x 系）で検証済みです。セットアップ時に現行バージョンを確認してください。

有効にするタイミング

• ✅ FastAPI（または任意の OpenAPI 3.1）の /openapi.json から型付き TS クライアント／SDK を生成する場合。
• ✅ スペックから TanStack Query フックまたは Zod のリクエスト／レスポンススキーマを生成する場合。
• ✅ 手書きまたは手動でメンテナンスしている API クライアントを、生成されたクライアントに置き換える場合。
• ✅ コントラクト変更時の再生成ワークフローと、CI での差分チェックを設定する場合。

次の場合は有効にしないでください：

• TanStack Query の 使用方法（キャッシュ、無効化、クエリーキー）が必要な場合は、tanstack-query スキルと組み合わせてください。このスキルで生成するのはフックのみです。
• バックエンド、OpenAPI スペック、または Pydantic モデルを作成する場合は、fastapi ／ pydantic-v2 スキルを使用してください。
• コントラクトが OpenAPI 3.0 のみで、3.0 に特化したツールが必要な場合、hey-api は 3.1 を対象としています（FastAPI ≥ 0.99 が出力する形式）。3.0 も読み取れますが、最適なのは 3.1 です。

ワークフロー

ステップ 1：インストール

ジェネレーターをインストールします。v0.73.0 以降、クライアントはジェネレーターに同梱されているため、クライアントパッケージを別途インストールする必要はありません：

npm install @hey-api/openapi-ts -D -E      # generator (pnpm/yarn/bun analogous)

ステップ 2：openapi-ts.config.ts を作成する

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

export default defineConfig({
  input: 'http://localhost:8000/openapi.json', // URL, file path, or a spec object
  output: 'src/client',                        // dir; or { path, format, lint }
  plugins: [
    '@hey-api/client-fetch',      // transport (fetch default; -axios / -next)
    '@tanstack/react-query',      // generated query/mutation hooks
    'zod',                        // generated request/response schemas
  ],
});

@hey-api/typescript（型）、@hey-api/sdk、@hey-api/schemas はデフォルトで含まれるコアプラグインです。スキーマ全体とすべてのオプションについては、references/configuration.md を参照してください。クライアントのトランスポートの詳細については、references/clients.md を参照してください。

ステップ 3：生成する

再現可能にするため、その場限りの実行ではなく package.json のスクリプトから実行します：

// package.json
"scripts": { "gen:api": "openapi-ts" }

npm run gen:api は openapi-ts.config.ts を読み込みます。単発で実行する CLI 形式は npx @hey-api/openapi-ts -i <input> -o <output> -c @hey-api/client-fetch です。

ステップ 4：SDK を使用する

各操作は型付きの非同期関数になります。デフォルトでは { data, error } の結果を返し、例外はスローしません。パラメーターは 1 つのオプションオブジェクト（path ／ query ／ body ／ headers）にまとめます：

const { data, error } = await getItem({ path: { id: 1 } });
if (error) { /* typed error */ } else { /* typed data */ }

関数が例外をスローするようにするには、throwOnError: true を（呼び出しごと、またはクライアント設定で）指定します。クライアント設定でベース URL を一度だけ設定してください。references/clients.md を参照してください。

ステップ 5：生成された TanStack Query フックと Zod スキーマを使用する

@tanstack/react-query プラグインは、TanStack Query に渡して使う <op>Options()、<op>QueryKey()、<op>InfiniteOptions()、<op>Mutation() ヘルパーを生成します。詳細は references/plugins-query-zod.md を参照してください。クエリー／ミューテーション／キャッシュのパターンについては、tanstack-query スキルを参照してください。zod プラグインは、境界での検証に使うスキーマを生成します（同じファイル内）。

ステップ 6：FastAPI の operationId と再生成／差分チェックのワークフロー

FastAPI のデフォルトの operationId は、分かりにくいメソッド名（createItemItemsPost）を生成します。references/fastapi-regen.md を参照し、generate_unique_id_function を使って生成元で修正してください。同ファイルでは、変更時に再生成するスクリプト、CI での差分チェック、コミットするか .gitignore に追加するかの判断についても説明しています。

ルール

厳守ルール（絶対に違反しないでください）：

• 生成ファイルを手動で編集しないでください。 再生成のたびに上書きされます。カスタマイズは設定やプラグインを使うか、SDK をラップしてください。src/client にパッチを当ててはいけません。
• OpenAPI コントラクトを唯一の信頼できる情報源としてください。 変更されたら再生成し、生成されたクライアントを仕様から乖離させないでください（CI の乖離チェックで徹底します）。
• ジェネレーターのバージョンを固定してください（-E／package.json で厳密に指定）。hey-api は 1.0 未満（0.x）で開発が速いため、バージョンを固定せずに更新すると出力が変わることがあります。セットアップ時に現在のバージョンを確認してください。
• 手書きではなく生成してください。 仕様を見ながら API 型や fetch ラッパーを手入力している場合は、作業を止めて生成してください。

推奨事項（必要に応じて変更できます）：

• プロジェクトで axios を標準採用している場合や Next.js アプリである場合を除き、デフォルトでは fetch クライアントを使用してください。
• レイヤーで throwOnError が必要な場合を除き、{ data, error } 形式（明示的なエラー処理）を維持してください。
• その場しのぎで各マシン上で実行するのではなく、コード生成は package.json のスクリプトと CI で実行してください。

注意点

• クライアントはジェネレーターにバンドルされています（v0.73.0 以降）。別途インストールしないでください。 plugins にクライアントを追加するだけです（fetch はデフォルトなので、指定も省略できます）。@hey-api/client-* をインストールしている v0.73 より前の設定を引き継いだ場合は、削除して再生成できます。（別の概念として、クライアントが自身の コード を生成出力にインライン化することがあります。これは出力オプションであり、インストールとは関係ありません。）
• FastAPI の operationId は冗長です。 generate_unique_id_function がない場合、createItemItemsPost のような名前になります。再生成のたびにきれいな状態になるよう、FastAPI 側で修正してください（references/fastapi-regen.md）。
• SDK 関数はデフォルトでは例外をスローしません。 { data, error } を返します。try/catch を使っていても error を確認しないコードは、失敗を黙って無視します。例外を使いたい場合は throwOnError: true を指定してください。
• OpenAPI 3.0 と 3.1 の違い。 hey-api は 3.1 を対象としています（FastAPI ≥ 0.99）。3.0 のみのドキュメントや、以前のコード生成に対する考え方（openapi-typescript-codegen は hey-api が置き換えた旧ツール）では、誤った前提につながります。3.1 の仕様に対して現行のツールを使用してください。
• 稼働中のサーバーから生成する場合と、保存済みの仕様から生成する場合。 URL を入力に指定すると、生成時にサーバーが起動している必要があり、API が変更されても気づかないまま再生成されます。コミット済みの仕様ファイルを使えば再現可能ですが、意図的に更新する必要があります。references/fastapi-regen.md の乖離対策に従って選択してください。

アンチパターン

• 「生成された型を少しだけ変更しよう。」 いいえ。次回の再生成で上書きされます。仕様を変更するか、出力をラップしてください。
• 「クライアントは手書きのほうが速い。」 すぐにコントラクトから乖離します。生成することがこの仕組みの目的です。
• 「生成されたクライアントをコミットして、そのまま放置しよう。」 CI の乖離チェックがなければ、API に対して気づかないまま古くなります。再生成後に git diff --exit-code を実行するゲートを追加してください。
• 「クエリのキャッシュや無効化についてもここで説明しよう。」 それは tanstack-query スキルの役割です。このスキルはフックの生成までを対象とします。

出力

設定された output ディレクトリに生成される、型付きクライアント（モデル、型付き SDK、プラグインに応じた TanStack Query フックと Zod スキーマ）に加え、openapi-ts.config.ts、gen:api スクリプト、そして（推奨）CI の乖離チェックです。これを利用するのは、生成された SDK とフックを通じて API を呼び出すフロントエンドコード（およびそのテスト／CI）です。

関連項目

• tanstack-query — クエリ／ミューテーション／キャッシュの使用方法。このスキルは、それらが利用するフックを生成します。
• fastapi／pydantic-v2 — このスキルが読み取る OpenAPI コントラクトを出力するバックエンドです。
• vite — 通常、生成されたクライアントを含む SPA ビルドです。

段階的な情報開示

• references/configuration.md — openapi-ts.config.ts を記述する際に読み込みます。input／output／plugins の完全なスキーマ、オプション、CLI フラグ、package.json との連携を説明します。
• references/clients.md — トランスポートを選択または設定する際に読み込みます。fetch／axios／next（およびその他）の詳細、ランタイム設定（setConfig、createClientConfig、呼び出しごとの設定）、ベース URL、クライアントコードの bundle オプションを説明します。
• references/plugins-query-zod.md — 生成された TanStack Query フックまたは Zod スキーマを組み込む際に読み込みます。生成されるエクスポート名と使い方、および tanstack-query スキルへの引き継ぎについて説明します。
• references/fastapi-regen.md — FastAPI と連携する際、または再生成を設定する際に読み込みます。operationId の修正、再生成スクリプト、CI での差分チェック、コミットと gitignore の使い分けについて説明します。
• references/sources.md — 調査の出典と事実確認のメモです。

本文の上限

• description は 1,024 文字以下、本文は約 500 行／5,000 トークン以下にしてください。大量の内容は references/ に記載します。