1. 導入：手動のAPI定義による「ズレ」を解消しよう
Web開発において、バックエンドの仕様変更に合わせてフロントエンドの型定義を手動で修正するのは、非常に手間がかかる上にミスが起きやすい作業です。もし、バックエンドの変更を検知して、フロントエンドのAPIクライアントやTypeScriptの型定義が自動的に更新されたらどうでしょうか？これを実現するのが「スキーマ駆動開発」です。今回は、OpenAPI（Swagger）仕様書からコードを自動生成するツール「Orval」を紹介します。
2. 基礎知識：スキーマ駆動開発とOrval
スキーマ駆動開発とは、APIの設計図であるOpenAPI定義ファイル（YAML/JSON）を「正」として、そこからコードを生成する開発手法のことです。これにより、バックエンドとフロントエンドの認識のズレがなくなります。
Orvalは、OpenAPIからTypeScriptの型定義だけでなく、AxiosやReact Queryなどで利用できるフックまでを一括生成してくれる強力なツールです。類似ツールにopenapi-generatorがありますが、Orvalは特にReactやTypeScript環境での開発体験（DX）に優れています。
3. 実装・解決策：Orvalによるコード自動生成の手順
まずはプロジェクトにOrvalをインストールします。
npm install -D orval
次に、プロジェクトのルートに orval.config.js という設定ファイルを作成します。ここで「どの仕様書から」「どのコードを生成するか」を指定します。
4. サンプルプログラム：orval.config.jsの設定例
// orval.config.js
module.exports = {
‘petstore’: {
// API仕様書のパスを指定
input: ‘./src/api/swagger.yaml’,
output: {
// 生成されるファイルの出力先
target: ‘./src/api/endpoints.ts’,
// APIクライアントのライブラリを指定（ここではAxios + React Query）
client: ‘react-query’,
// TypeScriptの型定義も自動生成
mode: ‘tags’,
},
},
};
設定後、以下のコマンドを実行するだけでAPIクライアントが生成されます。
npx orval –config orval.config.js
生成されたコードの利用例：
// 自動生成されたフックをコンポーネントで利用する例
import { useGetPets } from ‘./src/api/endpoints’;
const PetList = () => {
// 自動生成されたフックは型安全です
const { data, isLoading } = useGetPets();
if (isLoading) return
;
return
)}
;
};
5. 応用・注意点：現場で陥りやすい罠
型定義の乖離を防ぐための注意点：
生成されたファイルを直接編集してはいけません。仕様変更があった場合は、必ずYAMLファイルを修正し、コマンドで再生成してください。直接編集してしまうと、再生成時に変更が上書きされて消えてしまいます。
CI/CDへの組み込み：
現場では、バックエンドのCIパイプラインでOpenAPI定義を生成し、フロントエンドのビルド時にOrvalを走らせることで、常に最新の型定義を維持するのがベストプラクティスです。
自動生成を活用すれば、タイピングミスによるバグは過去のものになります。ぜひ、今日からプロジェクトに導入してみてください。
コメント