Hey API OpenAPI TS：OpenAPI仕様から型安全なTypeScript クライアント自動生成

この記事ではAIエージェントに特化して解説します。AIエージェント全般は AIエージェントフレームワーク比較2026年版 をご覧ください。

概要

Hey API OpenAPI TSは、OpenAPI仕様ファイルからTypeScript型安全クライアントを自動生成するコード生成ツールです。REST APIの定義を機械的に解析し、エンドポイント・リクエストボディ・レスポンス型を完全に型付けされたTypeScriptコードへ変換します。2024年時点でGitHubスター数は5,000を突破し、フロントエンド開発者の開発生産性向上を目指す実装主義的なツールとして位置付けられています。

データパイプラインの自動化をApache Airflowで行う場合にも、バックエンドAPIとの型安全な連携が不可欠です。Hey API OpenAPI TSはそのブリッジとして機能します。

コード生成フロー

OpenAPI仕様ファイルを入力としてTypeScriptクライアントが生成されるまでの流れを可視化します。

この一連の変換により、手書きのAPI型定義が不要になり、仕様変更があった際も npx openapi-ts を再実行するだけで型定義が最新状態に更新されます。

主な機能

• OpenAPI仕様の完全解析：OpenAPI 3.0・3.1仕様のスキーマ定義をパースし、型情報を逆流させ、エンドポイント全体をTypeScript型として復元できます。
• 自動型生成：リクエストパラメータ・ボディ・ヘッダー・レスポンスの構造を自動的にTypeScript型へ変換し、ランタイムエラーを開発段階で検出可能にします。
• 複数フレームワーク対応：axios・fetch API・Expressなど複数のHTTPクライアントライブラリに対応したコード出力が可能です。
• OpenAPI拡張機能サポート：x-vendor拡張やカスタムヘッダー定義などOpenAPIの拡張機能に対応し、ベンダー固有の仕様にも柔軟に応えます。
• 設定ファイルベースのカスタマイズ：openapi-ts.configファイルで生成ロジック・ディレクトリ構成・命名規則を細粒度で制御できます。
• バージョン管理対応：API仕様の更新時に差分を自動検出し、既存実装への影響を事前に把握できる変更差分レポート機能を搭載しています。

技術スタック

• 実装言語：TypeScript・JavaScript
• 対応環境：Node.js 16.x以上
• 出力ターゲット：TypeScript 4.5+、ECMAScript 2020以降
• HTTPクライアント対応：axios、fetch API、ky、node-fetch、superagent
• API仕様対応：OpenAPI 3.0.x、OpenAPI 3.1.x
• 開発依存：@swc/core（トランスパイル）、vitest（テスト）、zod（スキーマ検証）
• CI/CD統合：GitHub Actions、GitLab CI、npm scripts

導入方法

npmを使ったインストール：

npm install --save-dev @hey-api/openapi-ts

またはyarnを使用：

yarn add --dev @hey-api/openapi-ts

プロジェクトルートにopenapi-ts.config.tsを作成し、APIスキーマのパスを指定：

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

export default defineConfig({
  input: './api/openapi.json',
  output: {
    path: './src/generated',
    format: 'prettier',
  },
  client: 'fetch',
});

その後、コード生成を実行：

npx openapi-ts

生成されたコードはsrc/generatedディレクトリに自動出力されます。package.jsonのスクリプトに組み込むことで、ビルド時やプリコミットフックでの自動実行も可能です。

生成コードの活用例

生成されたクライアントを使ったAPIコールは次のように記述できます：

import { getUser, createPost } from './src/generated/sdk.gen';

// 型安全なGETリクエスト
const { data, error } = await getUser({ path: { userId: '123' } });
if (data) {
  console.log(data.name); // 型補完が効く
}

// 型安全なPOSTリクエスト
const result = await createPost({
  body: {
    title: '新規投稿',
    content: 'Hello World',
  },
});

パスパラメータ・クエリパラメータ・リクエストボディが全て型で保護されており、エディタ上でのオートコンプリートも正確に機能します。IDEが正しい型を提示するため、APIのドキュメントを別途参照する手間が大幅に削減されます。

ブラウザ自動化エージェント Browser Use と組み合わせることで、フロントエンドの操作テストと型安全なAPI検証を自動化パイプラインとして統合することも可能です。

競合比較

Hey API OpenAPI TSの最大の差別化ポイントは、TypeScriptフロントエンド開発者向けに最適化された軽量性と迅速なセットアップです。OpenAPI Generatorは言語横断的な標準ツールとして成熟していますが、Javaランタイムが必須で導入ハードルが高い。Orvalはフロントエンドのデータフェッチング層との連携に秀でていますが、バックエンド開発やAPI定義の標準化が目標の場合はOpenAPI Generatorが適切。Hey API OpenAPI TSは「最速で型安全なAPIクライアントを手に入れたい」というニーズに特化しています。

こんな人におすすめ

• フロントエンド開発者：APIスキーマから自動生成された型定義により、REST APIの呼び出し時にエディタの補完機能を最大活用でき、クエリパラメータやボディの誤記入を開発段階で防げます。
• 小～中規模チーム：セットアップが簡潔で設定ファイルも直感的なため、大掛かりなビルドシステム構築なしにOpenAPI自動生成の恩恵を受けられます。
• バージョン管理を重視する組織：API仕様更新時に生成コードの差分を自動検出し、変更が既存実装に与える影響を事前把握できるため、破壊的変更の検出が容易になります。
• Vue.js・React・SvelteのSPA開発者：フレームワークに依存しないコード生成により、複数プロジェクト間でのコード再利用性が高く、API層の実装パターン統一が実現できます。
• スキーマ駆動開発を推進している企業：OpenAPIスキーマを単一の真実の源泉（source of truth）として機能させ、ドキュメント・テスト・実装コードを一元管理するワークフローを構築できます。

参照ソース

• hey-api/openapi-ts - GitHub
• Hey API 公式ドキュメント
• OpenAPI Specification - openapis.org
• @hey-api/openapi-ts - npm