メインコンテンツへスキップ

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

     
     
    AIツールの開発・導入、業務システムの設計・構築を中心に活動しています。 lustage.jp 特定商取引法に基づく表記:gas-booking.lustage.jp/tokushoho

    あなたへのおすすめ