Type: String
.
Valid values: path to the file which will contains the implementation.
module.exports = {petstore: {output: {target: 'src/petstore.ts',},},};
Type: String | Function
.
Valid values: axios
, axios-functions
, angular
, react-query
, svelte-query
, vue-query
, zod
.
Default Value: axios-functions
.
module.exports = {petstore: {output: {client: 'react-query',},},};
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.
Type: String
.
Valid values: path to the folder where you want to generate all your models.
Default Value: same as the target.
module.exports = {petstore: {output: {schemas: './api/model',},},};
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
module.exports = {petstore: {output: {workspace: 'src/'target: './petstore.ts',},},};
Type: String
.
Valid values: single
, split
, tags
, tags-split
.
Default Value: single
.
module.exports = {petstore: {output: {mode: 'tags-split',},},};
Use to have one file with everything
module.exports = {petstore: {output: {target: 'src/petstore.ts',},},};
my-app└── src└── api└── endpoints└── petstore.ts
Here a single file petstore will be created in src with your specification implementation.
Use to have definition, implementation, schemas, mock in different files
module.exports = {petstore: {output: {target: 'src/petstore.ts',mode: 'split',},},};
my-app└── src├── petstore.definition.ts├── petstore.schemas.ts├── petstore.msw.ts└── petstore.ts
Here depending on the configuration, you will have multiple files named petstore with a prefix created in src.
For Angular:
petstore.ts is petstore.service.ts
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
module.exports = {petstore: {output: {target: 'src/petstore.ts',mode: 'tags',},},};
my-app└── src├── pets.ts└── 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.
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.
module.exports = {petstore: {output: {target: 'src/petstore.ts',mode: 'tags-split',},},};
my-app└── src├── petstore.schemas.ts└── pets├── petstore.ts├── petstore.definition.ts├── petstore.msw.ts└── 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.
Type: String
or Function
.
Valid values: path or implementation of the function.
module.exports = {output: {override: {title: (title) => `${title}Api`,},},};
Type: Boolean | Object | Function
.
Default Value: false
.
Will generate your mock using faker and msw by default (if value set to true).
module.exports = {petstore: {output: {mock: true,},},};
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:
module.exports = {petstore: {output: {mock: {type: 'msw',delay: 1000,useExamples: false,},},},};
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: String
.
Default Value: msw
.
Valid values: msw
, cypress
(coming soon).
Use to specify the mock type you want to generate.
Type: Number | Function
.
Default Value: 1000
.
Use to specify the delay time for the mock. It can either be a fixed number or a function that returns a number.
Type: Boolean
.
Gives you the possibility to use the example
/examples
fields from your OpenAPI specification as mock values.
Type: String
.
Give you the possibility to set base url to your mock handlers.
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
.
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.
Type: Boolean
.
Default Value: false
.
Can be used to prettier generated files. You need to have prettier in your dependencies.
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.
Type: Boolean
.
Use to enable the generation of the headers
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.
Type: String
.
Should be automatically found and transparent for you.
Can be used to specify the path to your package.json
.
Type: Object
.
Give you the possibility to override the output like your mock implementation or transform the API implementation like you want
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
module.exports = {petstore: {output: {override: {transformer: 'src/yourfunction.js',},},},};
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:
// based on AxiosRequestConfiginterface RequestConfig {method: 'get' | 'put' | 'patch' | 'post' | 'delete';url: string;params?: any;data?: any;responseType?: string;}
Example:
module.exports = {petstore: {output: {override: {mutator: {path: './api/mutator/custom-instance.ts',name: 'customInstance',// default: true},},},},};
// custom-instance.tsimport Axios, { AxiosRequestConfig } from 'axios';export const AXIOS_INSTANCE = Axios.create({ baseURL: '' });export const customInstance = <T>(config: AxiosRequestConfig): Promise<T> => {const source = Axios.CancelToken.source();const promise = AXIOS_INSTANCE({ ...config, cancelToken: source.token }).then(({ data }) => data,);// @ts-ignorepromise.cancel = () => {source.cancel('Query was cancelled by React Query');};return promise;};// 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 thisexport type ErrorType<Error> = AxiosError<Error>;
Example:
// custom-instance.tsimport Axios, { AxiosRequestConfig } from 'axios';import config from '@config';export const AXIOS_INSTANCE = Axios.create({ baseURL: '', ...config });export const customInstance = <T>(config: AxiosRequestConfig): Promise<T> => {const source = Axios.CancelToken.source();const promise = AXIOS_INSTANCE({ ...config, cancelToken: source.token }).then(({ data }) => data,);// @ts-ignorepromise.cancel = () => {source.cancel('Query was cancelled by React Query');};return promise;};export type ErrorType<Error> = AxiosError<Error>;
module.exports = {petstore: {output: {override: {mutator: {path: './api/mutator/custom-instance.ts',name: 'customInstance',alias: {'@config': path.resolve(_dirname, './src/config'),},},},},},};
react-query
, vue-query
and svelte-query
. You can also provide a hook like thisExample:
module.exports = {petstore: {output: {override: {mutator: {path: './api/mutator/use-custom-instance.ts',name: 'useCustomInstance',// default: true},},},},};
// use-custom-instance.tsimport Axios, { AxiosRequestConfig } from 'axios';import { useQueryClient } from 'react-query';export const AXIOS_INSTANCE = Axios.create({ baseURL: '' });export const useCustomInstance = <T>(): ((config: AxiosRequestConfig,) => Promise<T>) => {const token = useToken(); // Do what you wantreturn (config: AxiosRequestConfig) => {const source = Axios.CancelToken.source();const promise = AXIOS_INSTANCE({...config,headers: {Authorization: `Bearer ${token}`}cancelToken: source.token,}).then(({ data }) => data);// @ts-ignorepromise.cancel = () => {source.cancel('Query was cancelled by React Query');};return promise;};};export default useCustomInstance;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.
module.exports = {petstore: {output: {override: {header: (info: InfoObject): String[] => [`Generated by orval 🍺`,`Do not edit manually.`,...(info.title ? [info.title] : []),...(info.description ? [info.description] : []),...(info.version ? [`OpenAPI spec version: ${info.version}`] : []),],},},},};
Type: Object
.
Give you the possibility to override the generated query
module.exports = {petstore: {output: {...override: {query: {useQuery: true,useInfinite: true,useInfiniteQueryParam: 'nextId',options: {staleTime: 10000,},signal: true},},},...},};
Type: Boolean
.
Use to generate a useQuery custom hook. If the query key isn't provided that's the default hook generated.
Type: Boolean
.
Use to generate a useMutation custom hook.
Type: Boolean
.
Use to generate a useInfiniteQuery custom hook.
Type: Boolean
.
Use to generate a prefetching functions. This may be useful for the NextJS SSR or any prefetching situations.
Example generated function:
export const prefetchGetCategories = async <TData = Awaited<ReturnType<typeof getCategories>>,TError = ErrorType<unknown>,>(queryClient: QueryClient,options?: {query?: UseQueryOptions<Awaited<ReturnType<typeof getCategories>>,TError,TData,>,request?: SecondParameter<typeof customAxiosInstance>,},): Promise<QueryClient> => {const queryOptions = getGetCategoriesQueryOptions(options);await queryClient.prefetchQuery(queryOptions);return queryClient;};
Type: String
.
Use to automatically add to the request the query param provided by the useInfiniteQuery when you use getFetchMore
function.
Type: Object
.
Use to override the query config. Check available options here
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:
module.exports = {petstore: {output: {override: {query: {queryOptions: {path: './api/query/custom-query-options.ts',name: 'customQueryOptionsFn',// default: true},},},},},};
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:
module.exports = {petstore: {output: {override: {query: {mutationOptions: {path: './api/mutator/custom-mutator-options.ts',name: 'customMutatorOptionsFn',// default: true},},},},},};
Type: Boolean
.
Use to remove the generation of the abort signal provided by query
Type: Object
.
Give you specific options for the angular client
module.exports = {petstore: {output: {...override: {angular: {provideIn: 'any',},},},...},};
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
.
Type: Object
.
Give you the possibility to override the generated mock
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.
module.exports = {petstore: {output: {override: {mock: {properties: {'/tag|name/': 'jon', // Matches every property named 'tag' or 'name', including nested ones'/.*.user.id/': faker.string.uuid(), // Matches every property named 'id', inside an object named 'user', including nested onesemail: () => faker.internet.email(), // Matches only the property 'email''user.id': () => faker.string.uuid(), // Matches only the full path 'user.id'},},},},},};
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.
module.exports = {petstore: {output: {override: {mock: {format: {email: () => faker.internet.email(),iban: () => faker.finance.iban(),},},},},},};
Type: Boolean
.
Give you the possibility to set every property as required.
module.exports = {petstore: {output: {override: {mock: {required: true,},},},},};
Type: number
or Function
.
Give you the possibility to set delay time for mock. It can either be a fixed number or a function that returns a number.
Default Value: 1000
module.exports = {petstore: {output: {override: {mock: {delay: 0,},},},},};
Type: Number
.
Set the minimum length of generated arrays for properties that specify multiple items. (Default is 1
)
module.exports = {petstore: {output: {override: {mock: {arrayMin: 5,},},},},};
Type: Number
.
Set the maximum length of generated arrays for properties that specify multiple items. (Default is 10
)
module.exports = {petstore: {output: {override: {mock: {arrayMax: 15,},},},},};
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.
module.exports = {petstore: {output: {override: {mock: {useExamples: true,},},},},};
Type: String
.
Give you the possibility to set base url to your mock handlers. Will override the global option.
Type: Object
.
Give you the possibility to override the models
module.exports = {petstore: {output: {override: {components: {schemas: {suffix: 'DTO',},responses: {suffix: 'Response',},parameters: {suffix: 'Params',},requestBodies: {suffix: 'Bodies',},},},},},};
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.
module.exports = {petstore: {output: {override: {operations: {listPets: {transformer: 'src/yourfunction.js',mutator: 'src/response-type.js',mock: {properties: () => {return {id: () => faker.number.int({ min: 1, max: 99999 }),};},},},showPetById: {mock: {data: () => ({id: faker.number.int({ min: 1, max: 99 }),name: faker.person.firstName(),tag: faker.helpers.arrayElement([faker.word.sample(),undefined,]),}),},},},},},},};
Type: Object
.
Exactly the same as the override.operations
but this time you can do it by tags
Type: Function
.
// type signature(operation: OperationObject, route: string, verb: Verbs) => string;
Function to override the generate operation name.
Type: Object | Boolean
.
Use this property to provide a config to your http client or completely remove the request options property from the generated files.
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:
module.exports = {petstore: {output: {override: {formData: {path: './api/mutator/custom-form-data-fn.ts',name: 'customFormDataFn',// default: true},},},},};
// type signatureexport const customFormDataFn = <Body>(body: Body): FormData => {// do your implementation to transform it to FormDatareturn FormData;};
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:
module.exports = {petstore: {output: {override: {formUrlEncoded: {path: './api/mutator/custom-form-url-encoded-fn.ts',name: 'customFormUrlEncodedFn',// default: true},},},},};
// type signatureexport const customFormUrlEncodedFn = <Body>(body: Body): URLSearchParams => {// do your implementation to transform it to FormDatareturn URLSearchParams;};
Type: String
or Object
.
Valid values: path of the paramsSerializer function or object with a path and name.
Use this property to add a custom params serializer to all requests that use query params.
If you provide an object you can also add a default property to use an export default function.
Example:
module.exports = {petstore: {output: {override: {paramsSerializer: {path: './api/mutator/custom-params-serializer-fn.ts',name: 'customParamsSerializerFn',// default: true},},},},};
// type signatureexport const customParamsSerializerFn = (params: Record<string, any>,): string => {// do your implementation to transform the paramsreturn params;};
Type: Object
Use this property to add a default params serializer. Current options are: qs
.
All options are then passed to the chosen serializer.
Example:
module.exports = {petstore: {output: {override: {paramsSerializerOptions: {qs: {arrayFormat: 'repeat',},},},},},};
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:
module.exports = {petstore: {output: {override: {useDates: true,},},},};
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.
// type signatureconst client = axios.create({baseURL: '',});client.interceptors.response.use((originalResponse) => {handleDates(originalResponse.data);return originalResponse;});export default client;const isoDateFormat =/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d*)?(?:[-+]\d{2}:?\d{2}|Z)?$/;function isIsoDateString(value: any): boolean {return value && typeof value === 'string' && isoDateFormat.test(value);}export function handleDates(body: any) {if (body === null || body === undefined || typeof body !== 'object')return body;for (const key of Object.keys(body)) {const value = body[key];if (isIsoDateString(value)) {body[key] = new Date(value); // default JS conversion// body[key] = parseISO(value); // date-fns conversion// body[key] = luxon.DateTime.fromISO(value); // Luxon conversion// body[key] = moment(value).toDate(); // Moment.js conversion} else if (typeof value === 'object') {handleDates(value);}}}
Type: Boolean
Valid values: true or false. Defaults to false.
Use this property to convert OpenAPI int64
format to JavaScript BigInt
objects instead of number
.
Example:
module.exports = {petstore: {output: {override: {useBigInt: true,},},},};
Type: Boolean
Valid values: true or false. Defaults to false.
Use this property to enable type coercion for Zod schemas (only applies to query parameters schemas).
This is helpful if you want to use the zod schema to coerce (likely string-serialized) query parameters into the correct type before validation.
Example:
module.exports = {petstore: {output: {override: {coerceTypes: true,},},},};
Type: Boolean
.
Default Value: false
.
Generates the operation interfaces with named path parameters instead of individual arguments for each path parameter.
Example:
module.exports = {petstore: {output: {override: {useNamedParameters: true,},},},};
Type: Boolean
Valid values: true or false. Defaults to false.
Use this property to use TypeScript type
instead of interface
.
Example:
module.exports = {petstore: {output: {override: {useTypeOverInterfaces: true,},},},};
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:
module.exports = {petstore: {output: {override: {useDeprecatedOperations: false,},},},};
Type: Object
Use this property to include or exclude some content types
Example:
module.exports = {petstore: {output: {override: {contentType: {include: ['application/json'],exclude: ['application/xml'],},},},},};
Type: Boolean
Valid values: true or false. Defaults to false.
Use this property to generate native Typescript enum
instead of type
and const
combo.
Example:
module.exports = {petstore: {output: {override: {useNativeEnums: true,},},},};
Type: Boolean
Valid values: true or false. Defaults to false. Applies to all clients, but probably only makes sense for Tanstack Query.
Use this property to make all parameters optional. This is useful to take advantage of the Orval's auto-enable feature for Tanstack Query, see https://github.com/anymaniax/orval/pull/894
module.exports = {petstore: {output: {allParamsOptional: true,},},};
Type: Boolean
Valid values: true or false. Defaults to false. Note: this only works for Tanstack Query clients for now.
Use this property to enable URL encoding of path/query parameters. This is highly recommended, and will probably become a default in the future, see https://github.com/anymaniax/orval/pull/895
module.exports = {petstore: {output: {urlEncodeParameters: true,},},};