Orval - Generate type-safe API clients from OpenAPI

target

Path or URL to your OpenAPI specification.

Type: string | string[] | OpenApiDocument | Record<string, unknown>

orval.config.ts

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: './petstore.yaml',
    },
  },
});

You can also pass an array of targets. Orval will try each target in order and use the first one that resolves successfully (file exists on disk or URL is reachable). This is useful for fallback scenarios, such as preferring a local spec file when available while falling back to a remote URL.

orval.config.ts

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: [
        './local-petstore.yaml',
        'https://petstore.swagger.io/v2/swagger.json',
      ],
    },
  },
});

The shorthand input property supports arrays as well:

orval.config.ts

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: [
      './local-petstore.yaml',
      'https://petstore.swagger.io/v2/swagger.json',
    ],
  },
});

override

transformer

Transform the OpenAPI specification before generation.

Type: String | Function

orval.config.ts

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      override: {
        transformer: 'src/api/transformer/add-version.js',
      },
    },
  },
});

The transformer function receives an OpenApiDocument and should return a transformed OpenApiDocument. You can use the defineTransformer helper from orval for type inference.

transformer.ts

import { defineTransformer } from 'orval';

export default defineTransformer((inputSchema) => ({
  ...inputSchema,
  info: {
    ...inputSchema.info,
    title: `${inputSchema.info?.title} - Custom`,
  },
}));

See example transformer.

filters

Filter which endpoints to generate.

Default: {}

mode

Type: 'include' | 'exclude' Default: 'include'

orval.config.ts

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      filters: {
        mode: 'exclude',
        tags: ['pets'],
      },
    },
  },
});

schemas

Type: (String | RegExp)[]

Filter by schema names:

orval.config.ts

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      filters: {
        schemas: ['Error', /Cat/],
      },
    },
  },
});

parserOptions

Optional configuration for the OpenAPI spec parser, particularly useful for fetching specs from protected URLs.

headers

Type: Array<{ domains: string[]; headers: Record<string, string> }>

Domain-specific headers to send when fetching the OpenAPI specification from remote URLs. Headers are matched based on the domain of the URL being fetched.

orval.config.ts

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: 'https://api.example.com/openapi.json',
      parserOptions: {
        headers: [
          {
            domains: ['api.example.com'],
            headers: {
              Authorization: 'Bearer YOUR_TOKEN',
              'X-API-Key': 'your-api-key',
            },
          },
        ],
      },
    },
  },
});

Configure different headers for different domains:

orval.config.ts

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: 'https://api.example.com/openapi.json',
      parserOptions: {
        headers: [
          {
            domains: ['api.example.com', 'api.prod.example.com'],
            headers: {
              Authorization: 'Bearer PROD_TOKEN',
            },
          },
          {
            domains: ['api.dev.example.com'],
            headers: {
              Authorization: 'Bearer DEV_TOKEN',
            },
          },
        ],
      },
    },
  },
});

Input

target

override

transformer

filters

mode

tags

schemas

parserOptions

headers

On this page