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: stringnpm i -D openapi-typescript typescript
npm i openapi-fetch
npx openapi-typescript ./openapi/openapi.yaml -o ./src/api/schema.d.tsimport 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)が混在すると、生成される型が意図とずれます。
有料パートでは、それぞれの判断基準と回避策を、設定ファイルとワークフローの完成形で示します。