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: angular, axios, axios-functions, react-query, svelte-query, vue-query, swr, zod, fetch.

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.

httpClient

Type: String.

Valid values: fetch, axios.

Default Value: axios.

1 module.exports = {
2   petstore: {
3     output: {
4       client: 'swr',
5       httpClient: 'fetch',
6     },
7   },
8 };

If you want you can use the fetch API as an http client by specifying fetch in the httpClient option. httpClient only available when swr, react-query, vue-query, and svelte-query are specified as the client option.

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

fileExtension

Type: String.

Default Value: .ts.

Specify the file extension for files generated automatically. Modes such as tags, tags-split, and split do not alter schema files; they only pertain to client files.

1 module.exports = {
2   petstore: {
3     output: {
4       mode: 'split',
5       target: './gen/endpoints',
6       schemas: './gen/model',
7       fileExtension: '.gen.ts',
8     },
9   },
10 };

1 src/gen/
2 ├── endpoints
3 │   └── swaggerPetstore.gen.ts
4 └── model
5     ├── listPetsParams.ts
6     └── pets.ts

namingConvention

Type: String.

Valid values: camelCase, PascalCase, snake_case, kebab-case.

Default Value: camelCase.

Specify the naming convention for the generated files.

1 module.exports = {
2   petstore: {
3     output: {
4       namingConvention: 'PascalCase',
5       mode: 'split',
6       target: './gen/endpoints',
7       schemas: './gen/model',
8       fileExtension: '.gen.ts',
9     },
10   },
11 };

1 src/gen/
2 ├── endpoints
3 │   └── SwaggerPetstore.gen.ts
4 └── model
5     ├── ListPetsParams.ts
6     └── Pets.ts

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       mock: true,
6     },
7   },
8 };

1 my-app
2 └── src
3     └── petstore.ts

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

Value: split

Use to have implementation, schemas, mock in different files

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

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

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

• 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       mock: true,
6       mode: 'tags',
7     },
8   },
9 };

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       mock: true,
6       mode: 'tags-split',
7     },
8   },
9 };

1 my-app
2 └── src
3     ├── petstore.schemas.ts
4     └── pets
5         ├── petstore.msw.ts
6         └── 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.

indexFiles

Type: Boolean

Valid values: true or false. Defaults to true.

Specify whether to place index.ts in schemas generation.

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       schemas: 'src/gen/model',
5       indexFiles: false,
6     },
7   },
8 };

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

baseUrl

Type: String | Object.

Default Value: ''.

Allows you to set the baesUrl used for all API calls. This can either be a constant string or be configured to read from the servers field in the specification.

Example using constant:

1 module.exports = {
2   petstore: {
3     output: {
4       baseUrl: 'https://api.example.com', // prepend https://api.example.com to all api calls
5     },
6   },
7 };

getBaseUrlFromSpecification

Type: boolean

Set to true to make Orval read the url from the servers fields in the specification. If a path has defined a servers field, that url will be used, otherwise the url from the whole specification's servers field will be used. If set to false, a constant baseUrl must be set.

Example:

1 servers:
2   - url: https://api.example.com
3 paths:
4   /pets:
5     servers:
6       - url: https://pets.example.com

1 module.exports = {
2   petstore: {
3     output: {
4       baseUrl: {
5         getBaseUrlFromSpecification: true,
6         // prepend url defined in specification, in this example: 'https://api.example.com'
7         // for all calls, except for calls to /pets, which will instead use 'https://pets.example.com' as base url.
8       },
9     },
10   },
11 };

variables

Type: Dictionary.

Only valid when getBaseUrlFromSpecification is true. Used to substitute variables in urls. If the variable in the specification is an enum, and the provided value in the configuration is not one of the allowed values, an error will occur when generating. If a variable that is substituted is not configured, the default value defined in the specification will be used.

Example:

1 servers:
2   - url: https://{environment}.example.com/v1
3     variables:
4       environment:
5         default: api
6         enum:
7           - api
8           - api.dev
9           - api.staging

1 module.exports = {
2   petstore: {
3     output: {
4       baseUrl: {
5         getBaseUrlFromSpecification: true,
6         variables: {
7           environment: 'api.dev',
8         },
9       },
10     },
11   },
12 };

index

Type: Number.

Only valid when getBaseUrlFromSpecification is true. Since the servers field allows for multiple urls to be defined, you can decide which index of urls to pick here. If this is not defined, the first url will be used. If the defined index is out of range of the array, the last url in the array will be selected.

Example:

1 servers:
2   - url: https://api.example.com/v1
3   - url: https://api.dev.example.com/v1

1 module.exports = {
2   petstore: {
3     output: {
4       baseUrl: {
5         getBaseUrlFromSpecification: true,
6         index: 1,
7       },
8     },
9   },
10 };

baseUrl

Type: String.

Only valid when getBaseUrlFromSpecification is false. Behaves the same as setting the baseUrl as a string directly.

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       baseUrl: {
5         getBaseUrlFromSpecification: false,
6         baseUrl: 'https://api.example.com', // The same as setting petstore.output.baseUrl: 'https://api.example.com'
7       },
8     },
9   },
10 };

Gives the same result as:

1 module.exports = {
2   petstore: {
3     output: {
4       baseUrl: 'https://api.example.com',
5     },
6   },
7 };

mock

Type: Boolean | Object | Function.

Default Value: false.

Will generate your mock using faker and msw by default (if value set to true).

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

The mock options can take some properties to customize the generation if you set it to an object. If you set it to true, the default options will be used. The default options are:

1 module.exports = {
2   petstore: {
3     output: {
4       mock: {
5         type: 'msw',
6         delay: 1000,
7         useExamples: false,
8       },
9     },
10   },
11 };

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

To discover all the available options, read below.

type

Type: String.

Default Value: msw.

Valid values: msw, cypress (coming soon).

Use to specify the mock type you want to generate.

delay

Type: Number | Function | false.

Default Value: 1000.

Use to specify the delay time for the mock. It can either be a fixed number, false or a function that returns a number. Setting delay to false removes the delay call completely.

delayFunctionLazyExecute

Type: boolean.

Gives you the possibility to have functions that are passed to delay to be executed at runtime rather than when the mocks are generated.

useExamples

Type: Boolean.

Gives you the possibility to use the example/examples fields from your OpenAPI specification as mock values.

generateEachHttpStatus

Type: Boolean.

Gives you the possibility to generate mocks for all the HTTP statuses in the responses fields in your OpenAPI specification. By default only the 200 OK response is generated.

baseUrl

Type: String.

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

locale

Type: String.

Default Value: en.

Give you the possibility to set the locale for the mock generation. It is used by faker, see the list of available options here. It should also be strongly typed using defineConfig.

indexMockFiles

Type: Boolean

Default Value: false.

When true, adds a index.msw.ts file which exports all mock functions. This is only valid when mode is tags-split.

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       mode: 'tags-split',
5       mock: {
6         indexMockFiles: true,
7       },
8     },
9   },
10 };

docs

Type: Boolean | Object.

Default Value: false.

Will generate API docs using TypeDoc. by default these docs will be in Markdown format.

TypeDoc can be configured by passing the options to the docs object or by creating a config file e.g. typedoc.config.mjs in your project root (see the config docs for a full list of supported file names) or by passing a config filename to the configPath option below.

See the TypeDoc configuration documentation for more details.

The docs option can take some properties to customize the generation if you set it to an object. If you set it to true, the default options will be used.

When no output directory destination is specified in config, the file will be output to the docs directory by default.

For example configuration, see this sample.

configPath

Type: String.

Use to specify a TypeDoc config filename. This can be useful if your project already has a TypeDoc config for other docs.

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 careful 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.

biome

Type: Boolean.

Default Value: false.

You can apply lint and format of biome to the generated file. You need to have @biomejs/biome in your dependencies.

The automatically generated source code does not comply with some lint rules included in the default ruleset for biome, so please control them in the your biome configuration file.

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 GeneratorVerbOptions and should return a GeneratorVerbOptions

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

• If you use ES modules ("type": "module"). 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           extension: '.js',
9         },
10       },
11     },
12   },
13 };

The generated file will import the mutator with a .js extension.

header

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

fetch

Type: Object.

Give options to the generated fetch client.

1 module.exports = {
2   petstore: {
3     output: {
4       ...
5       override: {
6         fetch: {
7           includeHttpResponseReturnType: false,
8         },
9       },
10     },
11     ...
12   },
13 };

includeHttpResponseReturnType

Type: Boolean. Default: true

When using fetch for client or httpClient, the fetch response type includes http status for easier processing by the application. If you want to return a defined return type instead of an automatically generated return type, set this value to false.

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.

useMutation

Type: Boolean.

Use to generate a useMutation custom hook. The hook will only be generated if the operation is not a GET operation, and not configured to generate a query.

The operations override will take precedence if both are configured.

useInfinite

Type: Boolean.

Use to generate a useInfiniteQuery custom hook.

usePrefetch

Type: Boolean.

Use to generate a prefetching functions. This may be useful for the NextJS SSR or any prefetching situations.

Example generated function:

1 export const prefetchGetCategories = async <
2   TData = Awaited<ReturnType<typeof getCategories>>,
3   TError = ErrorType<unknown>,
4 >(
5   queryClient: QueryClient,
6   options?: {
7     query?: UseQueryOptions<
8       Awaited<ReturnType<typeof getCategories>>,
9       TError,
10       TData,
11     >,
12     request?: SecondParameter<typeof customAxiosInstance>,
13   },
14 ): Promise<QueryClient> => {
15   const queryOptions = getGetCategoriesQueryOptions(options);
16 
17   await queryClient.prefetchQuery(queryOptions);
18 
19   return queryClient;
20 };

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

queryKey

Type: String or Object.

Valid values: path of the queryKey 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           queryKey: {
7             path: './api/query/custom-query-key.ts',
8             name: 'customQueryKeyFn',
9             // default: true
10           },
11         },
12       },
13     },
14   },
15 };

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

mutationOptions

Type: String or Object.

Valid values: path of the mutationOptions 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           mutationOptions: {
7             path: './api/mutator/custom-mutator-options.ts',
8             name: 'useCustomMutatorOptions',
9             // default: true
10           },
11         },
12       },
13     },
14   },
15 };

1 // custom-mutator-options.ts
2 
3 export const useCustomMutatorOptions = <T, TError, TData, TContext>(
4   options: UseMutationOptions<T, TError, TData, TContext> &
5     Required<
6       Pick<UseMutationOptions<T, TError, TData, TContext>, 'mutationFn'>
7     >,
8   /* Optional */ path: { url: string },
9   /* Optional */ operation: { operationId: string; operationName: string },
10 ) => {
11   const queryClient = useQueryClient();
12   if (operation.operationId === 'createPet') {
13     queryClient.invalidateQueries({ queryKey: getGetPetsQueryKey() });
14   }
15   return options;
16 };

signal

Type: Boolean.

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

shouldExportMutatorHooks

Type: Boolean.

Default Value: true.

Use to stop the export of mutator hooks. Useful if you want to rely soley on useQuery, useSuspenseQuery, etc.

shouldExportQueryKey

Type: Boolean.

Default Value: true.

Use to stop the export of query keys.

shouldSplitQueryKey

Type: Boolean.

Default Value: false.

Use to make Orval generate query keys as arrays instead of strings.

version

Type: number.

Default Value: Detect from package json.

Use to specify a version for the generated hooks. This is useful if you want to force a version for the hooks.

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.

swr

Type: Object.

Give options to the generated swr client. It is also possible to extend the generated functions.

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

useInfinite

Type: Boolean.

Use to generate a useSWRInfinite custom hook.

swrOptions

Type: Object.

Use to override the useSwr options. Check available options here

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         swr: {
6           swrOptions: {
7             dedupingInterval: 10000,
8           },
9         },
10       },
11     },
12   },
13 };

swrMutationOptions

Type: Object.

Use to override the useSWRMutation options. Check available options here

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         swr: {
6           swrMutationOptions: {
7             revalidate: true,
8           },
9         },
10       },
11     },
12   },
13 };

swrInfiniteOptions

Type: Object.

Use to override the useSWRInfinite options. Check available options here

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         swr: {
6           swrInfiniteOptions: {
7             initialSize: 10,
8           },
9         },
10       },
11     },
12   },
13 };

zod

Type: Object.

Give you specific options for the zod client

1 module.exports = {
2   petstore: {
3     output: {
4       ...
5       override: {
6         zod: {
7           strict: {
8             response: true,
9             query: true,
10             param: true,
11             header: true,
12             body: true
13           },
14           coerce: {
15             response: true,
16               query: true,
17               param: true,
18               header: true,
19               body: true
20           },
21         },
22       },
23     },
24     ...
25   },
26 };

strict

Type: Object.

Default Value: false.

Use to set the strict mode for the zod schema. If you set it to true, the schema will be generated with the strict mode.

generate

Type: Object.

Default Value: true.

Use to set the which type of schemas you want to generate for the zod schema.

example:

1 module.exports = {
2   petstore: {
3     output: {
4       ...
5       override: {
6         zod: {
7           generate: {
8             param: true,
9             body: true,
10             response: false,
11             query: true,
12             header: true,
13           }
14         },
15       },
16     },
17     ...
18   },
19 };

In the above example exclude response body validations not generated

coerce

Type: Object.

Default Value: false.

Use to set the coerce for the zod schema. If you set it to true, the schema will be generated with the coerce on possible types.

You can also provide an array of coerce types to only generate the coerce types for the specified types.

example:

1 module.exports = {
2   petstore: {
3     output: {
4       ...
5       override: {
6         zod: {
7           coerce: {
8             response: [ 'boolean'],
9             query: ['string', 'number', 'boolean', 'bigint', 'date'],
10           }
11         },
12       },
13     },
14     ...
15   },
16 };

preprocess

Type: Object.

Use to add preprocess function to a zod schema. You can use a custom mutator to preprocess the data before it is validated.

example:

1 module.exports = {
2   petstore: {
3     output: {
4       ...
5       override: {
6         zod: {
7           preprocess: {
8             response: {
9               name: 'stripNill',
10               path: './src/mutators.ts',
11             },
12           },
13         },
14       },
15     },
16     ...
17   },
18 };

generateEachHttpStatus

Type: Boolean.

Gives you the possibility to generate mocks for all the HTTP statuses in the responses fields in your OpenAPI specification. By default only the 200 OK response is generated.

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

dateTimeOptions

Type: Object.

Default Value: {}.

Use to set options for zod datetime fields. These options are passed directly to zod datetime validation.

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         zod: {
6           dateTimeOptions: {
7             local: true,
8             offset: true,
9             precision: 3,
10           },
11         },
12       },
13     },
14   },
15 };

You can find more details in the zod documentation .

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 path 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', // Matches every property named 'tag' or 'name', including nested ones
8             '/.*.user.id/': faker.string.uuid(), // Matches every property named 'id', inside an object named 'user', including nested ones
9             email: () => faker.internet.email(), // Matches only the property 'email'
10             'user.id': () => faker.string.uuid(), // Matches only the full path 'user.id'
11           },
12         },
13       },
14     },
15   },
16 };

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 the default available format here.

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, Function or false.

Give you the possibility to set delay time for mock. It can either be a fixed number, false or a function that returns a number. Setting delay to false removes the delay call completely.

Default Value: 1000

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

delayFunctionLazyExecute

Type: boolean.

Gives you the possibility to have functions that are passed to delay to be executed at runtime rather than when the mocks are generated.

generateEachHttpStatus

Type: Boolean.

Gives you the possibility to generate mocks for all the HTTP statuses in the responses fields in your OpenAPI specification.

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

useExamples

An extension of the global mock option. If set to true, the mock generator will use the example property of the specification to generate the mock. If the example property is not set, the mock generator will fallback to the default behavior. Will override the global option.

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

baseUrl

Type: String.

Give you the possibility to set base url to your mock handlers. Will override the global option.

hono

Type: Object

Give you the possibility to override the generated hono

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         hono: {
6           handlers: 'src/handlers',
7           validatorOutputPath: 'src/validator.ts',
8           compositeRoute: 'src/routes.ts',
9         },
10       },
11     },
12   },
13 };

handlers

Type: String.

You can specify the output path for the hono handler.

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         hono: {
6           handlers: 'src/handlers',
7         },
8       },
9     },
10   },
11 };

Then it will be generated as below:

1 src/
2 ├── handlers
3 │   ├── createPets.ts
4 │   ├── listPets.ts
5 │   ├── showPetById.ts
6 │   └── updatePets.ts
7 ├── index.ts
8 ├── mutators.ts
9 ├── petstore.context.ts
10 ├── petstore.schemas.ts
11 ├── petstore.ts
12 ├── petstore.validator.ts
13 └── petstore.zod.ts

validatorOutputPath

Type: String.

You can change the validator output path

compositeRoute

Type: String.

You can output a file that defines a hono instance that composite routes.

Example:

1 module.exports = {
2   petstore: {
3     output: {
4       override: {
5         hono: {
6           compositeRoute: 'src/routes.ts',
7         },
8       },
9     },
10   },
11 };

Then it will be generated as below:

1 src/
2 ├── endpoints
3 │   ├── pets
4 │   │   ├── pets.context.ts
5 │   │   ├── pets.handlers.ts
6 │   │   └── pets.zod.ts
7 │   └── validator.ts
8 ├── routes.ts
9 └── schemas
10     ├── pet.ts
11     └── pets.ts

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.number.int({ min: 1, max: 99999 }),
13                 };
14               },
15             },
16           },
17           showPetById: {
18             mock: {
19               data: () => ({
20                 id: faker.number.int({ min: 1, max: 99 }),
21                 name: faker.person.firstName(),
22                 tag: faker.helpers.arrayElement([
23                   faker.word.sample(),
24                   undefined,
25                 ]),
26               }),
27             },
28           },
29         },
30       },
31     },
32   },
33 };