概要
Hey API OpenAPI TSは、OpenAPI仕様ファイルからTypeScript型安全クライアントを自動生成するコード生成ツールです。REST APIの定義を機械的に解析し、エンドポイント・リクエストボディ・レスポンス型を完全に型付けされたTypeScriptコードへ変換します。2024年時点でGitHubスター数は5,000を突破し、フロントエンド開発者の開発生産性向上を目指す実装主義的なツールとして位置付けられています。
主な機能
- 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のスクリプトに組み込むことで、ビルド時やプリコミットフックでの自動実行も可能。
競合比較
| 項目 | Hey API OpenAPI TS | OpenAPI Generator | Orval |
|---|---|---|---|
| 主な強み | TypeScript特化・軽量 | 多言語対応・標準化 | React Query統合 |
| 対応言語 | TypeScript / JavaScript | Java・Python・Go・C#ほか30言語以上 | TypeScript / JavaScript |
| セットアップ複雑度 | 非常にシンプル | 中程度（JVM必須） | 中程度 |
| カスタマイズ性 | プラグイン拡張可能 | テンプレートベース | APIクライアント層限定 |
| npm package size | 約2MB | 約500MB以上（Java環境） | 約5MB |
| React生態系統合 | 基本的なフェッチのみ | なし | TanStack Query統合 |
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）として機能させ、ドキュメント・テスト・実装コードを一元管理するワークフローを構築できます。