Output

target

Type: String.

Valid values: path to the file which will contains the implementation.

1 module.exports = {
2   petstore: {
3     output: {
4       target: 'src/petstore.ts',
5     },
6   },
7 };

client

Type: String | Function.

Valid values: axios, axios-functions, angular, react-query, svelte-query, vue-query.

Default Value: axios-functions.

1 module.exports = {
2   petstore: {
3     output: {
4       client: 'react-query',
5     },
6   },
7 };

if you want you can provide a function to extend or create you custom client generator and this function receive a GeneratorClients in argument and should return a ClientGeneratorsBuilder.

schemas

Type: String.

Valid values: path to the folder where you want to generate all your models.

Default Value: same as the target.

1 module.exports = {
2   petstore: {
3     output: {
4       schemas: './api/model',
5     },
6   },
7 };

workspace

Type: String.

Valid values: path to the folder which will contains all the generated files. This value will be use as a base for all the other path used in the orval config.

If you provide this option, an index.ts file will be also created with all the available exports

1 module.exports = {
2   petstore: {
3     output: {
4       workspace: 'src/'
5       target: './petstore.ts',
6     },
7   },
8 };

mode

Type: String.

Valid values: single, split, tags, tags-split.

Default Value: single.

1 module.exports = {
2   petstore: {
3     output: {
4       mode: 'tags-split',
5     },
6   },
7 };

Value: single

Use to have one file with everything

1 module.exports = {
2   petstore: {
3     output: {
4       target: 'src/petstore.ts',
5     },
6   },
7 };

1 my-app
2 └── src
3     └── api
4         └── endpoints
5             └── petstore.ts

Here a single file petstore will be created in src with your specification implementation.

Value: split

Use to have definition, implementation, schemas, mock in differents files

1 module.exports = {
2   petstore: {
3     output: {
4       target: 'src/petstore.ts',
5       mode: 'split',
6     },
7   },
8 };

1 my-app
2 └── src
3     ├── petstore.definition.ts
4     ├── petstore.schemas.ts
5     ├── petstore.msw.ts
6     └── petstore.ts

Here depending on the configuration, you will have multiple files named petstore with a prefix created in src.

petstore.definition.ts
petstore.schemas.ts
petstore.ts
petstore.msw.ts

For Angular:

petstore.ts is petstore.service.ts

Value: tags

Use this mode if you want one file by tag. Tag is a reference of the OpenApi specification tag. If you have a pets tag for all your pet calls then Orval will generate a file pets.ts in the target folder

1 module.exports = {
2   petstore: {
3     output: {
4       target: 'src/petstore.ts',
5       mode: 'tags',
6     },
7   },
8 };

1 my-app
2 └── src
3     ├── pets.ts
4     └── petstore.schemas.ts

For Angular:

petstore.ts is petstore.service.ts

If you don't use the schemas property only one file will be created with all the models for every tag.

Value: tags-split

This mode is a combination of the tags and split mode. Orval will generate a folder for every tag in the target folder and split into multiple files in those folders.

1 module.exports = {
2   petstore: {
3     output: {
4       target: 'src/petstore.ts',
5       mode: 'tags-split',
6     },
7   },
8 };

1 my-app
2 └── src
3     ├── petstore.schemas.ts
4     └── pets
5         ├── petstore.ts
6         ├── petstore.definition.ts
7         ├── petstore.msw.ts
8         └── petstore.ts

Same as the tags mode if you don't use the schemas property only one file will be created with all the models for every tag.

title

Type: String or Function.

Valid values: path or implementation of the function.

1 module.exports = {
2   output: {
3     override: {
4       title: (title) => `${title}Api`,
5     },
6   },
7 };

mock

Type: Boolean | Function.

Default Value: false.

Will generate your mock using faker and msw

1 module.exports = {
2   petstore: {
3     output: {
4       mock: true,
5     },
6   },
7 };

If you want you can provide a function to extend or create you custom mock generator and check here the type

clean

Type: Boolean | String[].

Default Value: false.

Can be used to clean generated files. Provide an array of glob if you want to customize what is deleted.

Be carefull clean all output target and schemas folder.

prettier

Type: Boolean.

Default Value: false.

Can be used to prettier generated files. You need to have prettier in your dependencies.

tslint

Type: Boolean.

Default Value: false.

Can be used to specify tslint (TSLint is deprecated in favour of eslint + plugins) as typescript linter instead of eslint. You need to have tslint in your dependencies.

headers

Type: Boolean.

Use to enable the generation of the headers

tsconfig

Type: String | Tsconfig.

Should be automatically found and transparent for you. Can be used to specify the path to your tsconfig or directly your config.

packageJson

Type: String.

Should be automatically found and transparent for you. Can be used to specify the path to your package.json.

override

Type: Object.

Give you the possibility to override the output like your mock implementation or transform the API implementation like you want

transformer

Type: String or Function.

Valid values: path or implementation of the transformer function.

This function is executed for each call when you generate and take in argument a VerbOptions and should return a VerbOptions

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         transformer: 'src/yourfunction.js',
6       },
7     },
8   },
9 };

mutator

Type: String or Object.

Valid values: path of the mutator function or object with a path and name.

If you provide an object you can also add a default property to use an export default function.

This function is executed for each call when this one is executed. It takes all the options passed to the verb as an argument and should return a promise with your custom implementation or preferred HTTP client.

Possible arguments:

The first argument will be an object with the following type.

1 // based on AxiosRequestConfig
2 interface RequestConfig {
3   method: 'get' | 'put' | 'patch' | 'post' | 'delete';
4   url: string;
5   params?: any;
6   data?: any;
7   responseType?: string;
8 }

The second argument is only provided for the Angular client and give an instance of HttpClient

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         mutator: {
6           path: './api/mutator/custom-instance.ts',
7           name: 'customInstance',
8           // default: true
9         },
10       },
11     },
12   },
13 };

1 // custom-instance.ts
2 
3 import Axios, { AxiosRequestConfig } from 'axios';
4 
5 export const AXIOS_INSTANCE = Axios.create({ baseURL: '' });
6 
7 export const customInstance = <T>(config: AxiosRequestConfig): Promise<T> => {
8   const source = Axios.CancelToken.source();
9   const promise = AXIOS_INSTANCE({ ...config, cancelToken: source.token }).then(
10     ({ data }) => data,
11   );
12 
13   // @ts-ignore
14   promise.cancel = () => {
15     source.cancel('Query was cancelled by React Query');
16   };
17 
18   return promise;
19 };
20 
21 // In some case with react-query and swr you want to be able to override the return error type so you can also do it here like this
22 export type ErrorType<Error> = AxiosError<Error>;

If your file have some alias you will also need to define them in the mutator object.

Example:

1 // custom-instance.ts
2 
3 import Axios, { AxiosRequestConfig } from 'axios';
4 import config from '@config';
5 
6 export const AXIOS_INSTANCE = Axios.create({ baseURL: '', ...config });
7 
8 export const customInstance = <T>(config: AxiosRequestConfig): Promise<T> => {
9   const source = Axios.CancelToken.source();
10   const promise = AXIOS_INSTANCE({ ...config, cancelToken: source.token }).then(
11     ({ data }) => data,
12   );
13 
14   // @ts-ignore
15   promise.cancel = () => {
16     source.cancel('Query was cancelled by React Query');
17   };
18 
19   return promise;
20 };
21 
22 export type ErrorType<Error> = AxiosError<Error>;

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         mutator: {
6           path: './api/mutator/custom-instance.ts',
7           name: 'customInstance',
8           alias: {
9             '@config': path.resolve(_dirname, './src/config'),
10           },
11         },
12       },
13     },
14   },
15 };

If you use one of the following clients react-query, vue-query and svelte-query. You can also provide a hook like this

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         mutator: {
6           path: './api/mutator/use-custom-instance.ts',
7           name: 'useCustomInstance',
8           // default: true
9         },
10       },
11     },
12   },
13 };

1 // use-custom-instance.ts
2 
3 import Axios, { AxiosRequestConfig } from 'axios';
4 import { useQueryClient } from 'react-query';
5 
6 export const AXIOS_INSTANCE = Axios.create({ baseURL: '' });
7 
8 export const useCustomInstance = <T>(): ((
9   config: AxiosRequestConfig,
10 ) => Promise<T>) => {
11   const token = useToken(); // Do what you want
12 
13   return (config: AxiosRequestConfig) => {
14     const source = Axios.CancelToken.source();
15     const promise = AXIOS_INSTANCE({
16       ...config,
17       headers: {
18         Authorization: `Bearer ${token}`
19       }
20       cancelToken: source.token,
21     }).then(({ data }) => data);
22 
23     // @ts-ignore
24     promise.cancel = () => {
25       source.cancel('Query was cancelled by React Query');
26     };
27 
28     return promise;
29   };
30 };
31 
32 export default useCustomInstance;
33 
34 export type ErrorType<Error> = AxiosError<Error>;

Type: Boolean | Function.

Default Value: true.

Use this property to disable the auto generation of the file header

You can provide a function to customize the way you want the generate the file header. You will receive the info object of the specification in argument and you should return an array of string.

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         header: (info: InfoObject): String[] => [
6           `Generated by orval 🍺`,
7           `Do not edit manually.`,
8           ...(info.title ? [info.title] : []),
9           ...(info.description ? [info.description] : []),
10           ...(info.version ? [`OpenAPI spec version: ${info.version}`] : []),
11         ],
12       },
13     },
14   },
15 };

query

Type: Object.

Give you the possibility to override the generated query

1 module.exports = {
2   petstore: {
3     output: {
4       ...
5       override: {
6         query: {
7           useQuery: true,
8           useInfinite: true,
9           useInfiniteQueryParam: 'nextId',
10           options: {
11             staleTime: 10000,
12           },
13           signal: true
14         },
15       },
16     },
17     ...
18   },
19 };

useQuery

Type: Boolean.

Use to generate a useQuery custom hook. If the query key isn't provided that's the default hook generated.

useInfinite

Type: Boolean.

Use to generate a useInfiniteQuery custom hook.

useInfiniteQueryParam

Type: String.

Use to automatically add to the request the query param provided by the useInfiniteQuery when you use getFetchMore function.

options (deprecated use queryOptions instead)

Type: Object.

Use to override the query config. Check available options here

queryOptions

Type: String or Object.

Valid values: path of the queryOptions function or object with a path and name.

If you provide an object you can also add a default property to use an export default function.

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         query: {
6           queryOptions: {
7             path: './api/query/custom-query-options.ts',
8             name: 'customQueryOptionsFn',
9             // default: true
10           },
11         },
12       },
13     },
14   },
15 };

mutatorOptions

Type: String or Object.

Valid values: path of the mutatorOptions function or object with a path and name.

If you provide an object you can also add a default property to use an export default function.

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         query: {
6           mutatorOptions: {
7             path: './api/mutator/custom-mutator-options.ts',
8             name: 'customMutatorOptionsFn',
9             // default: true
10           },
11         },
12       },
13     },
14   },
15 };

signal

Type: Boolean.

Use to remove the generation of the abort signal provided by query

angular

Type: Object.

Give you specific options for the angular client

1 module.exports = {
2   petstore: {
3     output: {
4       ...
5       override: {
6         angular: {
7           provideIn: 'any',
8         },
9       },
10     },
11     ...
12   },
13 };

provideIn

Type: Boolean or String.

Valid values: true, false, 'root', 'any', ''.

Default Value: 'root'.

Can be used to set the value of providedIn on the generated Angular services. If false, no providedIn will be set. If true or not specified, it will fall back to the default value: root.

mock

Type: Object.

Give you the possibility to override the generated mock

properties

Type: Object or Function.

You can use this to override the generated mock per property. Properties can take a function who take the specification in argument and should return un object or directly the object. Each key of this object can be a regex or directly the name of the property to override and the value can be a function which return the wanted value or directly the value. If you use a function this will be executed at runtime.

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         mock: {
6           properties: {
7             '/tag|name/': 'jon',
8             email: () => faker.internet.email(),
9           },
10         },
11       },
12     },
13   },
14 };

format

Type: Object.

Give you the possibility to put a value for a format. In your specification, if you put a format: email to a property Orval will automatically generate a random email for you. See here the default available format.

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         mock: {
6           format: {
7             email: () => faker.internet.email(),
8             iban: () => faker.finance.iban(),
9           },
10         },
11       },
12     },
13   },
14 };

required

Type: Boolean.

Give you the possibility to set every property as required.

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         mock: {
6           required: true,
7         },
8       },
9     },
10   },
11 };

delay

Type: number.

Give you the possibility to set delay time for mock

Default Value: 1000

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         mock: {
6           delay: 0,
7         },
8       },
9     },
10   },
11 };

arrayMin

Type: Number.

Set the minimum length of generated arrays for properties that specify multiple items. (Default is 1)

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         mock: {
6           arrayMin: 5,
7         },
8       },
9     },
10   },
11 };

arrayMax

Type: Number.

Set the maximum length of generated arrays for properties that specify multiple items. (Default is 10)

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         mock: {
6           arrayMax: 15,
7         },
8       },
9     },
10   },
11 };

baseUrl

Type: String.

Give you the possibility to set base url to your mock handlers.

components

Type: Object.

Give you the possibility to override the models

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         components: {
6           schemas: {
7             suffix: 'DTO',
8           },
9           responses: {
10             suffix: 'Response',
11           },
12           parameters: {
13             suffix: 'Params',
14           },
15           requestBodies: {
16             suffix: 'Bodies',
17           },
18         },
19       },
20     },
21   },
22 };

operations

Type: Object.

Give you the possibility to override the generated mock by operationId.

Each key of the object should be an operationId and take as value an object.

The value object can take the same properties as the override property (mutator,query,transformer,mock).

The mock options have one more possibility the data property. Which can take a function or the value directly. The function will be executed at runtime.

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         operations: {
6           listPets: {
7             transformer: 'src/yourfunction.js',
8             mutator: 'src/response-type.js',
9             mock: {
10               properties: () => {
11                 return {
12                   id: () => faker.datatype.number({ min: 1, max: 99999 }),
13                 };
14               },
15             },
16           },
17           showPetById: {
18             mock: {
19               data: () => ({
20                 id: faker.datatype.number({ min: 1, max: 99 }),
21                 name: faker.name.firstName(),
22                 tag: faker.helpers.arrayElement([
23                   faker.random.word(),
24                   undefined,
25                 ]),
26               }),
27             },
28           },
29         },
30       },
31     },
32   },
33 };

operationName

Type: Function.

1 // type signature
2 (operation: OperationObject, route: string, verb: Verbs) => string;

Function to override the generate operation name.

requestOptions

Type: Object | Boolean.

Use this property to provide a config to your http client or completly remove the request options property from the generated files.

formData

Type: Boolean or String or Object.

Valid values: path of the formData function or object with a path and name.

Use this property to disable the auto generation of form data if you use multipart

If you provide an object you can also add a default property to use an export default function.

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         formData: {
6           path: './api/mutator/custom-form-data-fn.ts',
7           name: 'customFormDataFn',
8           // default: true
9         },
10       },
11     },
12   },
13 };

1 // type signature
2 export const customFormDataFn = <Body>(body: Body): FormData => {
3   // do your implementation to transform it to FormData
4 
5   return FormData;
6 };

formUrlEncoded

Type: Boolean or String or Object.

Valid values: path of the formUrlEncoded function or object with a path and name.

Use this property to disable the auto generation of form url encoded

If you provide an object you can also add a default property to use an export default function.

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         formUrlEncoded: {
6           path: './api/mutator/custom-form-url-encoded-fn.ts',
7           name: 'customFormUrlEncodedFn',
8           // default: true
9         },
10       },
11     },
12   },
13 };

1 // type signature
2 export const customFormUrlEncodedFn = <Body>(body: Body): URLSearchParams => {
3   // do your implementation to transform it to FormData
4 
5   return URLSearchParams;
6 };

useDates

Type: Boolean

Valid values: true or false. Defaults to false.

Use this property to convert OpenAPI date or datetime to JavaScript Date objects instead of string.

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         useDates: true,
6       },
7     },
8   },
9 };

Note: You must provide and Axios converter to convert these to dates as this just makes the TypeScript definition a Date. You can choose to use any Date library you want like Moment, Luxon, or native JS Dates.

1 // type signature
2 const client = axios.create({
3   baseURL: '',
4 });
5 
6 client.interceptors.response.use((originalResponse) => {
7   handleDates(originalResponse.data);
8   return originalResponse;
9 });
10 
11 export default client;
12 
13 const isoDateFormat =
14   /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d*)?(?:[-+]\d{2}:?\d{2}|Z)?$/;
15 
16 function isIsoDateString(value: any): boolean {
17   return value && typeof value === 'string' && isoDateFormat.test(value);
18 }
19 
20 export function handleDates(body: any) {
21   if (body === null || body === undefined || typeof body !== 'object')
22     return body;
23 
24   for (const key of Object.keys(body)) {
25     const value = body[key];
26     if (isIsoDateString(value)) {
27       body[key] = new Date(value); // default JS conversion
28       // body[key] = parseISO(value); // date-fns conversion
29       // body[key] = luxon.DateTime.fromISO(value); // Luxon conversion
30       // body[key] = moment(value).toDate(); // Moment.js conversion
31     } else if (typeof value === 'object') {
32       handleDates(value);
33     }
34   }
35 }

useTypeOverInterfaces

Type: Boolean

Valid values: true or false. Defaults to false.

Use this property to use TypeScript type instead of interface.

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         useTypeOverInterfaces: true,
6       },
7     },
8   },
9 };

useDeprecatedOperations

Type: Boolean

Valid values: true or false. Defaults to true.

Use this property to include/exclude generating any operation marked "deprecated": true in OpenAPI.

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         useDeprecatedOperations: false,
6       },
7     },
8   },
9 };

contentType

Type: Object

Use this property to include or exclude some content types

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         contentType: {
6           include: ['application/json'],
7           exclude: ['application/xml'],
8         },
9       },
10     },
11   },
12 };

← PrevInput Next →Hooks

Edit this page on GitHub

Was this page helpful?

Output

target

client

schemas

workspace

mode

Value: single

Value: split

Value: tags

Value: tags-split

title

mock

clean

prettier

tslint

headers

tsconfig

packageJson

override

transformer

mutator

header

query

useQuery

useInfinite

useInfiniteQueryParam

options (deprecated use queryOptions instead)

queryOptions

mutatorOptions

signal

angular

provideIn

mock

properties

format

required

delay

arrayMin

arrayMax

baseUrl

components

operations

tags

operationName

requestOptions

formData

formUrlEncoded

useDates

useTypeOverInterfaces

useDeprecatedOperations

contentType

On this page

Resources

Community