APIクライアントを手書きしない:OpenAPIから型安全なTypeScriptクライアントを自動生成する
バックエンドがAPIの仕様を変えたのに、フロント側の型が古いまま——ビルドは通るのに、実行時に `undefined` を触って落ちる。この手の事故は、APIクライアントを手書きしている かぎり定期的に起きます。人間が仕様書とコードを目視で同期し続けるのは、そもそも無理があります。
この記事では、OpenAPIの仕様から型安全なTypeScriptクライアントを自動生成する アプローチを、選び方も含めて実務目線でまとめます。AIにコードを書かせる時代だからこそ、この「型の土台」が効いてきます。
なぜ生成なのか:仕様とコードを一致させ続ける
OpenAPI(旧Swagger)は、APIのエンドポイント・パラメータ・レスポンス構造を機械可読な形で記述する仕様です。これを入力に型やクライアントを自動生成すれば、フロントとバックの型がずれない状態を機械的に保てます。
静的なTypeScriptの型は実行時コストがゼロで、クライアントの容量も増やしません。仕様が変われば生成し直すだけで、型エラーが「どこを直すべきか」を教えてくれます。
2026年の主な選択肢
用途に応じて、代表的なツールは次のように使い分けます。
openapi-typescript + openapi-fetch:仕様から型だけを生成し、Fetch APIの薄い型付きラッパーで叩く。軽量で、余計なランタイムを持ち込みたくないときに向く。
Orval:型安全なクライアントに加え、React Query・SWR・Vue Query などのフックまで生成する。データ取得層ごと任せたいときに強い。
openapi-zod-client:Zodスキーマを生成し、レスポンスを実行時にも検証 したいケースに向く。
型は「コンパイル時の安心」しかくれない。外部APIのレスポンスが仕様通りとは限らないなら、Zodで実行時検証まで足すと堅くなる。
最小の導入イメージ
openapi-typescript を使う場合、生成はコマンド一つです。
npx openapi-typescript ./openapi.yaml -o ./src/api/schema.d.tsあとは openapi-fetch でクライアントを作ると、パスもレスポンスも補完が効きます。
import createClient from 'openapi-fetch';
import type { paths } from './api/schema';
const client = createClient<paths>({ baseUrl: '/api' });
const { data, error } = await client.GET('/users/{id}', {
params: { path: { id: 123 } },
});AI駆動開発との相性がいい理由
コーディングエージェントにAPI連携を任せると、ときどき「それっぽいが実在しないフィールド」を書きます。生成された型が入っていれば、こうしたハルシネーションはその場で型エラーとして弾かれます。AIの生成量が増えるほど、正しさを機械的に担保する土台の価値は上がります。
導入の勘所
生成物はコミットするか、CIで毎回生成するかを最初に決めます。仕様(openapi.yaml)を単一の正とし、生成コードは手で編集しない ルールを徹底することが、破綻を防ぐ最大のコツです。既存プロジェクトなら、まず型生成だけを入れて、クライアント生成やフック生成へ段階的に広げるのが安全です。
この記事を書いた人
TypeScriptによる型安全な設計や、API連携の内製開発もご相談いただけます。
Lustage(ラステージ) は、AI・Google Apps Script・TypeScript を活用した業務自動化・社内システム開発を行っています。「この作業、自動化できないかな?」という現場のお困りごとがあれば、お気軽にご相談ください。
▶ 公式サイト: https://lustage.jp