orval

Orval OpenAPI のベストプラクティス

Orval を使用して OpenAPI 仕様から型安全な TypeScript クライアントを生成するための包括的なガイドです。8 つのカテゴリにわたる 42 のルールを、影響度の高い順にまとめ、自動設定、クライアント生成、テスト設定の指針を示します。

適用するタイミング

以下の場合に、これらのガイドラインを参照してください。

• 新しいプロジェクトで Orval を設定するとき
• OpenAPI ベースの TypeScript クライアント生成を設定するとき
• React Query、SWR、または Vue Query を、生成されたフックと統合するとき
• 認証やエラー処理のためのカスタムミューテーターを作成するとき
• テスト用に MSW モックを生成するとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	OpenAPI 仕様の品質	CRITICAL	spec-
2	設定アーキテクチャ	CRITICAL	orvalcfg-
3	出力構造と整理	HIGH	output-
4	カスタムクライアントとミューテーター	HIGH	mutator-
5	クエリーライブラリとの統合	MEDIUM-HIGH	oquery-
6	型安全性と検証	MEDIUM	types-
7	モック生成とテスト	MEDIUM	mock-
8	高度なパターン	LOW	adv-

クイックリファレンス

1. OpenAPI 仕様の品質（CRITICAL）

• spec-operationid-unique - 一意で説明的な operationId を使用する
• spec-schemas-reusable - 再利用可能なスキーマを components で定義する
• spec-tags-organization - タグを使ってオペレーションを整理する
• spec-response-types - すべてのレスポンスタイプを明示的に定義する
• spec-required-fields - 必須フィールドを明示的に指定する

2. 設定アーキテクチャ（CRITICAL）

• orvalcfg-mode-selection - API の規模に基づいて出力モードを選択する
• orvalcfg-client-selection - フレームワークの要件に基づいてクライアントを選択する
• orvalcfg-separate-schemas - スキーマを専用ディレクトリに分ける
• orvalcfg-input-validation - 生成前に OpenAPI 仕様を検証する
• orvalcfg-baseurl-setup - ベース URL を適切に設定する
• orvalcfg-prettier-format - コードの自動フォーマットを有効にする

3. 出力構造と整理（HIGH）

• output-file-extension - 生成コードには専用のファイル拡張子を使用する
• output-index-files - インポートを整理するために index ファイルを生成する
• output-naming-convention - 一貫した命名規則を設定する
• output-clean-target - 一貫した再生成のためにクリーンモードを有効にする
• output-headers-enabled - 生成された関数でヘッダーを有効にする

4. カスタムクライアントとミューテーター（HIGH）

• mutator-custom-instance - HTTP クライアントの設定にカスタムミューテーターを使用する
• mutator-error-types - ミューテーターからカスタムエラー型をエクスポートする
• mutator-body-wrapper - リクエスト変換用のボディ型ラッパーをエクスポートする
• mutator-interceptors - 横断的な関心事にはインターセプターを使用する
• mutator-token-refresh - ミューテーターでトークンのリフレッシュを処理する
• mutator-fetch-client - バンドルサイズを小さくするために fetch ミューテーターを使用する

5. クエリーライブラリとの統合（MEDIUM-HIGH）

• oquery-hook-options - デフォルトのクエリーオプションをグローバルに設定する
• oquery-key-export - キャッシュ無効化用にクエリーキーをエクスポートする
• oquery-infinite-queries - ページネーション対応エンドポイントで無限クエリーを有効にする
• oquery-suspense-support - ストリーミング UX のためにサスペンスモードを有効にする
• oquery-signal-cancellation - リクエストのキャンセル用に AbortSignal を渡す
• oquery-mutation-callbacks - 生成されたミューテーションオプションの型を使用する

6. 型安全性と検証（MEDIUM）

• types-zod-validation - 実行時検証用に Zod スキーマを生成する
• types-zod-strict - より安全な検証のために Zod の strict モードを有効にする
• types-zod-coerce - 型変換に Zod の coercion を使用する
• types-use-dates - Date 型の生成に useDates を有効にする
• types-bigint-support - 大きな整数を扱えるように useBigInt を有効にする

7. モック生成とテスト（中）

• mock-msw-generation - テスト用の MSW ハンドラーを生成します
• mock-use-examples - 現実的なモックに OpenAPI の例を使用します
• mock-delay-config - モックの応答遅延を設定します
• mock-http-status - すべての HTTP ステータスコードのモックを生成します
• mock-index-files - 簡単にセットアップできるよう、モックのインデックスファイルを生成します

8. 高度なパターン（低）

• adv-input-transformer - 入力トランスフォーマーを使用して、仕様を前処理します
• adv-operation-override - オペレーションごとに設定を上書きします
• adv-output-transformer - 出力トランスフォーマーを使用して、生成されたコードを変更します
• adv-form-data-handling - フォームデータのシリアライズを設定します

使用方法

詳しい説明とコード例については、個々のリファレンスファイルをお読みください。

• セクション定義 - カテゴリー構成と影響レベル
• ルールテンプレート - 新しいルールを追加するためのテンプレート
• 例：spec-operationid-unique

関連スキル

• 生成されたフックの使用については、tanstack-query スキルをご覧ください
• 生成された API クライアントのモックについては、test-msw スキルをご覧ください
• スキーマの検証については、zod スキルをご覧ください

完全版ドキュメント

すべてのルールを展開した完全なガイド：AGENTS.md