【TypeScript】OpenAPI自動型生成の実践ガイド - 効率的なAPI型定義の構築方法

概要

OpenAPIを使って定義されたAPIスキーマからTypeScriptの型定義を自動生成することで、型定義の手間が省けるだけでなく、API変更時の対応もスムーズになります。特に、手動での型定義はエラーが発生しやすく、APIの変更に伴う修正が漏れがちです。本記事では、OpenAPIからの型自動生成方法とおすすめのツールについて解説し、実践的な導入方法を紹介します。

OpenAPI自動型生成のメリット

最新の型を常に保持できる

APIのスキーマが更新された際、自動生成スクリプトを実行するだけで最新の型定義が取得でき、変更を反映する手間が大幅に削減できます。これにより、フロントエンドとバックエンドの整合性を保つことが容易になります。

人為的なミスを防げる

手動で型定義を行うと、プロパティの抜けや型の誤設定といったミスが発生しがちです。自動生成は、スキーマに基づいて正確な型を出力するため、エラーの発生が抑えられます。

開発効率が向上

一度型定義を生成する環境を整えておけば、スクリプトを再実行するだけで型更新が可能になるため、開発効率が向上します。特にAPIエンドポイントが多いプロジェクトでは、この効果が顕著です。

OpenAPIからTypeScriptの型定義を自動生成するツール

openapi-typescript

openapi-typescriptは、OpenAPI仕様のスキーマからTypeScript型を生成するためのシンプルで高速なツールです。使い方が簡単で、多くのプロジェクトで採用されています。

インストール

npm install -g openapi-typescript

基本的な使用方法

以下のコマンドでスキーマから型ファイルを生成できます。

openapi-typescript http://localhost:8000/api/schema/ --output ./types/api-types.ts

特徴

• 型定義の構造が見やすく、自動補完機能が有効になります。
• JSONスキーマに基づいて厳密な型が生成されるため、APIドキュメントの変更を即座に反映できます。

swagger-typescript-api

swagger-typescript-apiは、OpenAPI仕様に基づいて型定義だけでなくAPI呼び出し関数まで生成できるため、さらに効率的です。

インストール

npm install swagger-typescript-api --save-dev

使用方法

次のコマンドで、API呼び出し関数と型定義を一括で生成します。

npx swagger-typescript-api -p http://localhost:8000/api/schema/ -o ./src/api

特徴

• 型とAPI呼び出しのコードが同時に生成され、APIコールが簡単に行えるようになります。
• フロントエンドからのAPI操作が簡素化され、コールエラーも型チェックで防げます。

自動型生成をプロジェクトに導入する手順

型生成スクリプトの追加

型生成のプロセスを手動で行うのではなく、スクリプトで一元化します。次の例では、package.jsonにスクリプトを追加します。

"scripts": {
  "generate:types": "openapi-typescript http://localhost:8000/api/schema/ --output ./types/api-types.ts"
}

このスクリプトを実行することで、スキーマから最新の型定義がtypes/api-types.tsに出力されます。

型生成とビルドを自動化

開発時に型生成が行われるよう、型生成スクリプトをprebuildスクリプトとして設定すると、ビルド前に常に最新の型定義が生成されます。

"scripts": {
  "prebuild": "npm run generate:types",
  "build": "tsc"
}

CI/CDパイプラインでの型生成

型生成スクリプトは、CI/CDのパイプラインにも組み込み可能です。これにより、デプロイ前に常に最新の型定義が生成されるため、APIの変更により型が不一致になることを防げます。

型定義ファイルの管理方法

型定義ファイルは、他のファイルと区別して専用ディレクトリで管理するのが一般的です。たとえば、typesフォルダを作成し、ここに自動生成されたファイルを保存します。

tsconfig.jsonでの設定

tsconfig.jsonにおいて、生成された型ファイルをプロジェクト内で認識させるために、includeに指定します。

{
  "compilerOptions": {
    "strict": true,
    "outDir": "./dist",
  },
  "include": ["src//*", "types/api-types.ts"]
}

型ファイルのバージョン管理

自動生成された型ファイルもバージョン管理に含めることで、変更のトラッキングが容易になります。更新が多発する場合は、生成スクリプトの実行タイミングを工夫し、不要な更新が発生しないように注意しましょう。

実際の開発での活用例

自動生成された型定義を活用し、axiosでAPIデータを取得するコードを例に示します。

// apiClient.ts
import axios from "axios";
import { User } from "../types/api-types";  // 自動生成された型定義をインポート
async function fetchUser(id: number): Promise<User> {
    const response = await axios.get<User>(`http://localhost:8000/api/users/${id}`);
    return response.data;
}

この例では、レスポンスの型がUserであることをTypeScriptに伝えることで、フロントエンド側での型チェックが行われ、エラーを未然に防ぐことができます。

ベストプラクティス

• 型ファイルの一元管理: 自動生成された型定義を一か所で管理し、プロジェクト内での使用を明確にします。
• 自動化スクリプトの活用: 開発フローやCI/CDに組み込み、常に最新の型が生成されるようにします。
• OpenAPIスキーマの管理: OpenAPIスキーマが正確であることが、自動生成される型の信頼性に直結するため、スキーマ管理を徹底します。

まとめ

OpenAPI自動型生成を活用することで、TypeScriptでAPIを利用する際に最新の型定義が自動的に反映され、開発の効率化と型安全性が向上します。特 に、型定義の更新が頻繁に必要なプロジェクトでは、自動化ツールの導入は効果的です。開発の生産性を高めるため、ぜひ実践的に活用してみてください。