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

OpenAPIからTS型とクライアントを自動生成しCIで差分検知

    画像


    OpenAPIからTS型とクライアントを自動生成しCIで差分検知

    型の手書きはなぜ壊れるのか

    フロントとバックエンドで型を別々に手書きすると、仕様変更のたびにズレが入ります。たとえばバックエンドが user.name を user.displayName に改名したとします。フロントの interface User は手書きなので、コンパイルは通ったまま本番で undefined が表示されます。TypeScriptの型は実行時には消えるので、手書きの型は「そうあってほしい」という願望を書いたものにすぎません。

    対策は、OpenAPIの定義ファイルをSingle Source of Truthにすることです。型とクライアントはそこから機械的に作り、手で直さないようにします。

    「型を生成すれば安全」とは限らない

    型生成を入れれば安全になると思われがちですが、実際には保証の範囲が限られます。openapi-typescriptが出力するのはランタイムを持たない(runtime-free)型です。そのためサーバーが仕様と違うJSONを返しても、実行時には検知されません。守れるのは「仕様と呼び出しコードの整合」までです。「実装と仕様の整合」は別の仕組みで守る必要があります。この記事は前者を、CIで機械的に守る構成を扱います。

    代表ツールの特徴と選定軸

    • openapi-typescript(7.13.0 / 2026年2月公開): OpenAPI 3.0と3.1の型を生成するツールで、Swagger 2系は5.x以前が対象です。型だけを出し、実行コードは生成しません。

    • openapi-fetch(0.17.0): 上の型を読み込む薄いfetchクライアントです。サイズは6kbで、ランタイムはほぼゼロとされています。

    • Hey API(@hey-api/openapi-ts、0系): SDK、型、Zodスキーマ、TanStack Queryフックなどをプラグインで生成します。Vercel、OpenCode、PayPalが使っているコード生成ツールと紹介されています。由来も特徴的で、openapi-typescript-codegenがメンテナンスされなくなったためフォークし、OpenAPI 3.1に対応させたものです。

    • Orval(8系): OpenAPI v3とSwagger v2から型安全なクライアントを生成します。React、Vue、Svelte、Angular向けのフックやモックまで一括で出せます。

    • openapi-generator: Java製の汎用ジェネレーターで、多言語対応が強みです。実行にJava環境が要ります。

    選定軸は次の4つです。

    1. 生成物が型だけか、実行コードを含むか

    2. OpenAPI 3.1への対応

    3. TanStack Queryなど既存スタックとの相性

    4. 差分検知のしやすさ(出力が決定的か)

    更新頻度はツールごとに大きく違います。Snykの履歴では、Orvalは8.37.0(2026年9月23日)から8.46.0(10月30日)まで、約5週間で10バージョンを出しています。一方openapi-typescriptの7.13.0は2月公開のままです。更新が速いツールで生成物をコミットする場合は、バージョン更新だけで生成物が変わります。そのためツールのバージョン固定が、差分検知を安定させる前提になります。

    この記事で組む構成

    openapi.yaml → 型生成 → 型安全クライアント → CIで生成物の差分検知

    完成時のディレクトリ構成は次のとおりです。

    • openapi/

    • openapi.yaml(唯一の仕様)

    • src/api/

    • schema.d.ts(自動生成・手編集禁止)

    • client.ts(クライアント初期化)

    • .github/workflows/

    • api-types.yml(再生成して差分があれば失敗)

    • package.json、tsconfig.json

    前提知識は、TypeScriptの基礎、Node.js 20以上の環境、GitHub Actionsの基本的な書き方です。

    動く最小例

    最小の仕様から型を作り、型付きで呼び出します。

    openapi: 3.1.0
    info:
      title: Sample API
      version: 1.0.0
    paths:
      /users/{id}:
        get:
          operationId: getUser
          parameters:
            - name: id
              in: path
              required: true
              schema:
                type: integer
          responses:
            "200":
              description: OK
              content:
                application/json:
                  schema:
                    type: object
                    required: [id, displayName]
                    properties:
                      id:
                        type: integer
                      displayName:
                        type: string
    npm i -D openapi-typescript typescript
    npm i openapi-fetch
    npx openapi-typescript ./openapi/openapi.yaml -o ./src/api/schema.d.ts
    import createClient from "openapi-fetch";
    import type { paths } from "./schema";
    
    const client = createClient<paths>({ baseUrl: "https://api.example.com" });
    
    export async function showUser(): Promise<void> {
      const { data, error } = await client.GET("/users/{id}", {
        params: { path: { id: 1 } },
      });
      if (error || !data) {
        throw new Error("取得に失敗しました");
      }
      console.log(data.displayName);
    }

    data は2XXのときだけ、error は4XX/5XXのときだけ存在します。そのため error の確認だけでは data が undefined の可能性が残り、!data でも絞り込んでから使います。

    仕様側で displayName を name に改名して再生成すると、data.displayName がその場でコンパイルエラーになります。冒頭の手書き型で起きた問題を、ビルド時に検出できる形になります。

    有料パートで扱う内容

    • 生成スクリプトとツールのバージョン固定

    • tsconfig の設定(noUncheckedIndexedAccess など)

    • 認証ヘッダーやエラー処理を入れるミドルウェア

    • GitHub Actionsで再生成し、git diff --exit-code で差分を検知するワークフロー

    • 仕様のlintと破壊的変更の検知

    • Hey APIやOrvalに切り替える場合の差分

    導入時に踏みやすい落とし穴

    • 生成物をコミットするか: コミットすればレビューで差分が見えますが、再生成を忘れる事故が増えます。コミットしない場合は、CIとローカルでビルド前に必ず生成する運用が必要です。

    • スキーマのバージョン管理: 仕様を別リポジトリに置くと、どのコミットを参照するかが曖昧になります。

    • OpenAPI 3.0と3.1の記法差: nullable: true(3.0)と type: [string, "null"](3.1)が混在すると、生成される型が意図とずれます。

    有料パートでは、それぞれの判断基準と回避策を、設定ファイルとワークフローの完成形で示します。

     
     
    AIや自動化ツールの使い方・設定手順を、調べたことの整理を兼ねてまとめています。同じところでつまずいた方の参考になれば嬉しいです。

    あなたへのおすすめ