Configuration

This page is a reference to the different ways of configuring your orval projects.

Using an orval-config.js configuration file, placed at the root of a project, you can provide a list of options that changes the default behaviour of the orval generated files.

Configuration options for the following are described on this page:

orval.config.js

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

Input

target

Type: String.

Valid values: path or link to the specification.

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

validation

Type: Boolean.

Default Value: false.

To enforce the best quality as possible of specification, we have integrated the amazing OpenAPI linter from IBM. We strongly encourage you to setup your custom rules with a .validaterc file, you can find all useful information about this configuration here.

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

override

Type: Object.

Give you the possibility to override the specification

transformer

Type: String or Function.

Valid values: path or implementation of the transformer function.

This function is executed when you generate and take in argument an OpenAPIObject and should return an OpenAPIObject.

1 module.exports = {
2   input: {
3     override: {
4       transformer: 'src/api/transformer/add-version.js',
5     },
6   },
7 };

Example of transformer here

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.

Valid values: axios, angular, react-query.

Default Value: axios.

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

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 };

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:

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:

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.

Default Value: false.

Will generate your mock using faker and msw

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

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 shouled return a VerbOptions

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

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 prefered 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 is only provided for the angular client and give an instance of HttpClient

Example:

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

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 };

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           config: {
11             staleTime: 10000,
12           },
13         },
14       },
15     },
16     ...
17   },
18 };

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.

config

Type: Object.

Use to override the query config. Check available options here

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   input: {
3     override: {
4       mock: {
5         properties: {
6           '/tag|name/': 'jon',
7           email: () => faker.internet.email(),
8         },
9       },
10     },
11   },
12 };

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   input: {
3     override: {
4       mock: {
5         format: {
6           email: () => faker.internet.email(),
7           iban: () => faker.finance.iban(),
8         },
9       },
10     },
11   },
12 };

required

Type: Boolean.

Give you the possibility to set every property required.

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   input: {
3     override: {
4       operations: {
5         listPets: {
6           transformer: 'src/yourfunction.js',
7           mutator: 'src/response-type.js',
8           mock: {
9             properties: () => {
10               return {
11                 id: () => faker.random.number({ min: 1, max: 99999 }),
12               };
13             },
14           },
15         },
16         showPetById: {
17           mock: {
18             data: () => ({
19               id: faker.random.number({ min: 1, max: 99 }),
20               name: faker.name.firstName(),
21               tag: faker.helpers.randomize([faker.random.word(), undefined]),
22             }),
23           },
24         },
25       },
26     },
27   },
28 };

tags

Type: Object.

Exactly the same as the override.operations but this time you can do it by tags

Full example

1 const faker = require('faker');
2 
3 module.exports = {
4   petstore: {
5     output: {
6       mode: 'split',
7       target: 'src/petstore.ts',
8       schemas: 'src/model',
9       client: 'react-query',
10       mock: true,
11       override: {
12         operations: {
13           listPets: {
14             mutator: 'src/response-type.js',
15             mock: {
16               properties: () => {
17                 return {
18                   id: () => faker.random.number({ min: 1, max: 99999 }),
19                 };
20               },
21             },
22           },
23           showPetById: {
24             mock: {
25               data: () => ({
26                 id: faker.random.number({ min: 1, max: 99 }),
27                 name: faker.name.firstName(),
28                 tag: faker.helpers.randomize([faker.random.word(), undefined]),
29               }),
30             },
31           },
32         },
33         mock: {
34           properties: {
35             '/tag|name/': () => faker.name.lastName(),
36           },
37         },
38       },
39     },
40     input: {
41       target: './petstore.yaml',
42       override: {
43         transformer: 'src/add-version.js',
44       },
45     },
46   },
47 };