orval

Orval - OpenAPI から TypeScript コードを生成するツール

Orval は、OpenAPI v3／Swagger v2 の仕様から、型安全な TypeScript クライアント、フック、スキーマ、モック、サーバーハンドラーを生成します。

クイックスタート

インストール

npm install orval -D
# or yarn add orval -D
# or pnpm add orval -D
# or bun add orval -D

最小限の設定

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: './petstore.yaml',
    },
    output: {
      target: './src/api/petstore.ts',
      schemas: './src/api/model',
      client: 'react-query',
    },
  },
});

実行

npx orval
npx orval --config ./orval.config.ts
npx orval --project petstore
npx orval --watch

セットアップの選択

クライアント選択ガイド

ユースケース	クライアント	httpClient	備考
サーバー状態を扱う React	react-query	fetch または axios	TanStack Query のフック
サーバー状態を扱う Vue 3	vue-query	fetch または axios	Vue 向け TanStack Query
サーバー状態を扱う Svelte	svelte-query	fetch または axios	Svelte 向け TanStack Query
単独の SolidJS アプリ	solid-query	fetch または axios	Solid 向け TanStack Query
フルスタックの SolidStart	solid-start	ネイティブの fetch	query()／action() プリミティブを使用します
シグナルを使う Angular	angular-query	angular	注入可能な関数、シグナルによるリアクティブ性
従来型の Angular	angular	—	HttpClient サービス
SWR を使う React	swr	fetch または axios	Vercel SWR のフック
軽量／エッジ	fetch	—	依存関係がなく、どこでも動作します
Node.js／既存の Axios	axios-functions	—	ファクトリー関数（デフォルト）
DI を使う Axios	axios	—	注入可能な Axios インスタンス
バリデーションのみ	zod	—	Zod スキーマ、HTTP クライアントなし
バックエンド API サーバー	hono	—	Zod バリデーション付き Hono ハンドラー
AI エージェントツール	mcp	—	Model Context Protocol サーバー

モード選択ガイド

• single — すべてを 1 つのファイルにまとめます。小規模な API に最適です。
• split — ファイルを分割します：petstore.ts、petstore.schemas.ts、petstore.msw.ts。中規模の API に適しています。
• tags — OpenAPI のタグごとに 1 つのファイルを作成し、スキーマを共有します。ドメインごとに整理できます。
• tags-split — タグごとにフォルダーを作成し、ファイルを分割します。大規模な API に最適です。推奨です。

httpClient オプション

react-query、vue-query、svelte-query、swr クライアントの場合：

output: {
  client: 'react-query',
  httpClient: 'fetch',  // 'fetch' (default) | 'axios'
}

angular-query の場合：

output: {
  client: 'angular-query',
  httpClient: 'angular',  // Uses Angular HttpClient
}

設定リファレンス

設定の構造

import { defineConfig } from 'orval';

export default defineConfig({
  [projectName]: {
    input: InputOptions,
    output: OutputOptions,
    hooks: HooksOptions,
  },
});

複数のプロジェクトで、入力／出力設定を変えて同じ設定ファイルを共有できます。

入力オプション

input: {
  target: './spec.yaml',              // Path or URL to OpenAPI spec (required)
  override: {
    transformer: './transform.js',    // Transform spec before generation
  },
  filters: {
    mode: 'include',                  // 'include' | 'exclude'
    tags: ['pets', /health/],         // Filter by OpenAPI tags
    schemas: ['Pet', /Error/],        // Filter by schema names
  },
  parserOptions: {
    headers: [                        // Auth headers for remote spec URLs
      {
        domains: ['api.example.com'],
        headers: {
          Authorization: 'Bearer YOUR_TOKEN',
          'X-API-Key': 'your-api-key',
        },
      },
    ],
  },
}

出力オプション

output: {
  target: './src/api/endpoints.ts',     // Output path (required)
  client: 'react-query',               // Client type (see table above)
  httpClient: 'fetch',                  // 'fetch' (default) | 'axios' | 'angular'
  mode: 'tags-split',                   // 'single' | 'split' | 'tags' | 'tags-split'
  schemas: './src/api/model',           // Output path for model types
  operationSchemas: './src/api/params', // Separate path for operation-derived types
  workspace: 'src/',                    // Base folder for all files
  fileExtension: '.ts',                 // Custom file extension
  namingConvention: 'camelCase',        // File naming: camelCase | PascalCase | snake_case | kebab-case
  indexFiles: true,                     // Generate index.ts barrel files
  clean: true,                          // Clean output before generating
  prettier: true,                       // Format with Prettier
  biome: true,                          // Format with Biome
  headers: true,                        // Generate header parameters
  baseUrl: '/api/v2',                   // API base URL
  // or from spec:
  // baseUrl: { getBaseUrlFromSpecification: true, index: 0, variables: { environment: 'api.dev' } },
  mocks: true,                          // Generate MSW + Faker mocks (boolean, object, or function)
  docs: true,                           // Generate TypeDoc documentation
  // docs: { configPath: './typedoc.config.mjs' },
  allParamsOptional: true,              // Make all params optional (except path params)
  urlEncodeParameters: true,            // URL-encode path/query parameters
  optionsParamRequired: false,          // Make options parameter required
  propertySortOrder: 'Specification',   // 'Alphabetical' | 'Specification'
  tsconfig: './tsconfig.json',          // Custom tsconfig path
  override: { ... },                    // Advanced overrides (see below)
}

複数の API 仕様

export default defineConfig({
  petstoreV1: {
    input: { target: './specs/v1.yaml' },
    output: { target: 'src/api/v1', client: 'react-query' },
  },
  petstoreV2: {
    input: { target: './specs/v2.yaml' },
    output: { target: 'src/api/v2', client: 'react-query' },
  },
});

エンドポイントのフィルタリング

input: {
  target: './spec.yaml',
  filters: {
    mode: 'include',
    tags: ['pets'],
  },
}

詳細ガイド

ユーザーの質問が以下の特定のトピックに関する場合は、このスキルのディレクトリにある対応するファイルを読んでください。

トピック	ファイル	ユーザーが次の内容について尋ねた場合に読み込む
TanStack Query / SWR	tanstack-query.md	React Query、Vue Query、Svelte Query、Solid Query、SWR、クエリフック、無効化、無限クエリ、サスペンス、プリフェッチ
Angular	angular.md	Angular Query、Angular HttpClient、シグナル、inject 関数、Angular サービス、providedIn
SolidStart	solid-start.md	SolidStart、@solidjs/router、query()、action()、createAsync、revalidate
カスタム HTTP / 認証	custom-http-clients.md	カスタムミューテーター、認証、トークン、インターセプター、カスタム fetch/axios、baseURL、フックベースのミューテーター
Zod バリデーション	zod-validation.md	Zod スキーマ、バリデーション、実行時バリデーション、coerce、strict、preprocess
モック / MSW	mocking-msw.md	MSW モック、テスト、テストセットアップ、faker、Vitest、モックハンドラー、useExamples
Hono サーバー	hono.md	Hono ハンドラー、zValidator、複合ルート、コンテキスト型、サーバーサイド生成
高度な設定	advanced-config.md	型生成、列挙型、操作ごとのオーバーライド、FormData、JSDoc、params シリアライザー、完全な例
ツール / ワークフロー	tooling-workflow.md	プログラム API、トランスフォーマー、フック、NDJSON ストリーミング、MCP、afterAllFilesWrite

OpenAPI 仕様のベストプラクティス

1. 各操作に一意の operationId を使用する — Orval は関数名とフック名にこれらを使用します
2. 再利用可能なスキーマを components/schemas に定義する — 生成される型の重複を減らせます
3. タグを使用して操作をグループ化する — tags モードと tags-split モードで機能します
4. すべての操作にレスポンス型を定義する — 完全な型安全性を実現できます
5. 必須フィールドを指定する — 生成される TypeScript インターフェースの省略可能／必須に影響します
6. 数値の列挙型には x-enumNames を使用する — 読みやすい const 名が生成されます
7. example の値を指定する — useExamples: true の場合、モック生成で使用されます
8. ストリーミングエンドポイントには application/x-ndjson コンテンツタイプを使用する — 型付き NDJSON の生成が可能になります

CLI リファレンス

orval                                    # Generate using auto-discovered config
orval --config ./api/orval.config.ts     # Specify config file
orval --project petstore                 # Run specific project(s)
orval --watch                            # Watch mode
orval --watch ./src                      # Watch specific directory
orval --clean                            # Clean generated files
orval --prettier                         # Format with Prettier
orval --biome                            # Format with Biome
orval --tsconfig ./src/tsconfig.json     # Custom tsconfig path
orval --mode split                       # Override output mode
orval --client react-query               # Override client
orval --mock                             # Override mock generation
orval --input ./spec.yaml --output ./api.ts  # Direct generation

リソース

• ドキュメント
• GitHub
• サンプルプロジェクト