输出配置

target

类型：String。

有效值：包含实现的文件路径。

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

client

类型：String | Function。

有效值：angular、axios、axios-functions、react-query、svelte-query、vue-query、swr、zod、fetch。

默认值：axios-functions。

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

如果您想要扩展或创建自定义客户端生成器，可以提供一个函数，该函数接收 GeneratorClients 作为参数，并应返回 ClientGeneratorsBuilder。

httpClient

类型：String。

有效值：fetch、axios。

默认值：axios。

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

如果您想使用 fetch API 作为 http 客户端，可以在 httpClient 选项中指定 fetch。 httpClient 仅在 client 选项指定为 swr、react-query、vue-query 和 svelte-query 时可用。

schemas

类型：String。

有效值：要生成所有模型的文件夹路径。

默认值：与 target 相同。

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

fileExtension

类型：String。

默认值：.ts。

指定自动生成文件的文件扩展名。tags、tags-split 和 split 等模式不会改变 schema 文件；它们只涉及 client 文件。

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

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

namingConvention

类型：String。

有效值：camelCase、PascalCase、snake_case、kebab-case。

默认值：camelCase。

指定生成文件的命名约定。

如果您要查找属性键的命名约定，请参见 namingConvention。

1module.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};

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

workspace

类型：String。

有效值：包含所有生成文件的文件夹路径。此值将用作 orval 配置中使用的所有其他路径的基础。

如果您提供此选项，还将创建一个包含所有可用导出的 index.ts 文件

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

mode

类型：String。

有效值：single、split、tags、tags-split。

默认值：single。

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

值：single

用于将所有内容放在一个文件中

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

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

这里将在 src 中创建一个包含您的规范实现的单个 petstore 文件。

值：split

用于将实现、模式、模拟放在不同的文件中

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

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

根据配置，您将在 src 中创建多个以 petstore 命名并带有前缀的文件。

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

对于 Angular：

petstore.ts 是 petstore.service.ts

值：tags

如果您希望每个标签一个文件，请使用此模式。标签是 OpenAPI 规范标签的引用。如果您的所有宠物调用都有一个 pets 标签，那么 Orval 将在目标文件夹中生成一个 pets.ts 文件

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

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

对于 Angular：

petstore.ts 是 petstore.service.ts

如果您不使用 schemas 属性，将只创建一个包含每个标签所有模型的文件。

值：tags-split

此模式是标签和拆分模式的组合。Orval 将在目标文件夹中为每个标签生成一个文件夹，并在这些文件夹中拆分为多个文件。

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

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

与标签模式相同，如果您不使用 schemas 属性，将只创建一个包含每个标签所有模型的文件。

indexFiles

类型：Boolean

有效值：true 或 false。默认为 true。

指定是否在 schemas 生成中放置 index.ts。

示例：

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

title

类型：String 或 Function。

有效值：函数的路径或实现。

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

baseUrl

类型：String | Object。

默认值：''。

允许您设置用于所有 API 调用的 baseUrl。这可以是常量字符串，也可以配置为从规范中的 servers 字段读取。

使用常量的示例：

1module.exports = {
2  petstore: {
3    output: {
4      baseUrl: 'https://api.example.com', // 为所有 api 调用添加前缀 https://api.example.com
5    },
6  },
7};

getBaseUrlFromSpecification

类型：boolean

设置为 true 使 Orval 从规范中的 servers 字段读取 url。如果路径定义了 servers 字段，将使用该 url，否则将使用整个规范的 servers 字段中的 url。如果设置为 false，必须设置常量 baseUrl。

示例：

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

1module.exports = {
2  petstore: {
3    output: {
4      baseUrl: {
5        getBaseUrlFromSpecification: true,
6        // 为所有调用添加规范中定义的 url 前缀，在此示例中：'https://api.example.com'
7        // 除了对 /pets 的调用，它将使用 'https://pets.example.com' 作为基础 url。
8      },
9    },
10  },
11};

variables

类型：Dictionary。

仅在 getBaseUrlFromSpecification 为 true 时有效。用于替换 url 中的变量。如果规范中的变量是枚举，并且配置中提供的值不是允许值之一，生成时将发生错误。如果要替换的变量未配置，将使用规范中定义的默认值。

示例：

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

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

index

类型：Number。

仅在 getBaseUrlFromSpecification 为 true 时有效。由于 servers 字段允许定义多个 url，您可以在此决定选择哪个 url 索引。如果未定义，将使用第一个 url。如果定义的索引超出数组范围，将选择数组中的最后一个 url。

示例：

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

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

baseUrl

类型：String。

仅在 getBaseUrlFromSpecification 为 false 时有效。行为与直接将 baseUrl 设置为字符串相同。

示例：

1module.exports = {
2  petstore: {
3    output: {
4      baseUrl: {
5        getBaseUrlFromSpecification: false,
6        baseUrl: 'https://api.example.com', // 与设置 petstore.output.baseUrl: 'https://api.example.com' 相同
7      },
8    },
9  },
10};

与以下设置结果相同：

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

mock

类型：Boolean | Object | Function。

默认值：false。

默认情况下（如果值设置为 true），将使用 faker 和 msw 生成您的模拟数据。

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

如果将其设置为对象，模拟选项可以接受一些属性来自定义生成。如果设置为 true，将使用默认选项。默认选项为：

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

如果您想要扩展或创建自定义模拟生成器，可以提供一个函数，并在这里查看类型。

要了解所有可用选项，请阅读下文。

type

类型：String。

默认值：msw。

有效值：msw、cypress（即将推出）。

用于指定要生成的模拟类型。

delay

类型：Number | Function | false。

默认值：1000。

用于指定模拟的延迟时间。它可以是固定数字、false 或返回数字的函数。将 delay 设置为 false 会完全移除延迟调用。

delayFunctionLazyExecute

类型：boolean。

为您提供将传递给 delay 的函数在运行时执行而不是在生成模拟时执行的可能性。

useExamples

类型：Boolean。

为您提供使用 OpenAPI 规范中的 example/examples 字段作为模拟值的可能性。

generateEachHttpStatus

类型：Boolean。

为您提供为 OpenAPI 规范中 responses 字段中的所有 HTTP 状态生成模拟的可能性。默认情况下只生成 200 OK 响应。

baseUrl

类型：String。

为您提供为模拟处理程序设置基础 url 的可能性。

locale

类型：String。

默认值：en。

为您提供为模拟生成设置区域设置的可能性。它由 faker 使用，可用选项列表请参见这里。使用 defineConfig 时也应该是强类型的。

indexMockFiles

类型：Boolean

默认值：false。

当为 true 时，添加一个导出所有模拟函数的 index.msw.ts 文件。这仅在 mode 为 tags-split 时有效。

示例：

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

docs

类型：Boolean | Object。

默认值：false。

将使用 TypeDoc 生成 API 文档。默认情况下，这些文档将采用 Markdown 格式。

TypeDoc 可以通过将选项传递给 docs 对象来配置，或者通过在项目根目录中创建配置文件（例如 typedoc.config.mjs）（支持的文件名完整列表请参见配置文档），或者通过将配置文件名传递给下面的 configPath 选项来配置。

更多详细信息请参见 TypeDoc 配置文档。

如果将 docs 选项设置为对象，它可以接受一些属性来自定义生成。如果设置为 true，将使用默认选项。

当 config 中未指定输出目录目标时，文件将默认输出到 docs 目录。

配置示例请参见此示例。

configPath

类型：String。

用于指定 TypeDoc 配置文件名。如果您的项目已经有用于其他文档的 TypeDoc 配置，这会很有用。

clean

类型：Boolean | String[]。

默认值：false。

可用于清理生成的文件。如果要自定义删除的内容，请提供 glob 数组。

小心清理所有输出目标和模式文件夹。

prettier

类型：Boolean。

默认值：false。

可用于美化生成的文件。您需要全局安装 prettier。

biome

类型：Boolean。

默认值：false。

您可以对生成的文件应用 biome 的 lint 和 format。您需要在依赖项中包含 @biomejs/biome。

自动生成的源代码不符合 biome 默认规则集中包含的某些 lint 规则，因此请在您的 biome 配置文件中控制它们。

headers

类型：Boolean。

用于启用头部的生成

tsconfig

类型：String | Tsconfig。

应该自动找到并对您透明。可用于指定 tsconfig 的路径或直接指定您的配置。

packageJson

类型：String。

应该自动找到并对您透明。可用于指定 package.json 的路径。

override

类型：Object。

为您提供覆盖输出的可能性，如您的模拟实现或按您想要的方式转换 API 实现

transformer

类型：String 或 Function。

有效值：转换器函数的路径或实现。

此函数在生成时为每个调用执行，接受 GeneratorVerbOptions 作为参数，并应返回 GeneratorVerbOptions

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

mutator

类型：String 或 Object。

有效值：mutator 函数的路径或包含路径和名称的对象。

如果您提供对象，还可以添加 default 属性来使用导出默认函数。

此函数在每次调用时执行。它将传递给动词的所有选项作为参数，并应返回带有您的自定义实现或首选 HTTP 客户端的 promise。

可能的参数：

第一个参数将是具有以下类型的对象。

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

第二个参数仅为 Angular 客户端提供，并给出 HttpClient 的实例

示例：

1module.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
3import Axios, { AxiosRequestConfig } from 'axios';
4
5export const AXIOS_INSTANCE = Axios.create({ baseURL: '' });
6
7export 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// 在某些情况下，使用 react-query 和 swr 时，您希望能够覆盖返回错误类型，因此您也可以在这里这样做
22export type ErrorType<Error> = AxiosError<Error>;

如果您的文件有一些别名，您还需要在 mutator 对象中定义它们。

示例：

1// custom-instance.ts
2
3import Axios, { AxiosRequestConfig } from 'axios';
4import config from '@config';
5
6export const AXIOS_INSTANCE = Axios.create({ baseURL: '', ...config });
7
8export 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
22export type ErrorType<Error> = AxiosError<Error>;

1module.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};

如果您使用以下客户端之一：react-query、vue-query 和 svelte-query。您也可以像这样提供一个钩子

示例：

1module.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
3import Axios, { AxiosRequestConfig } from 'axios';
4import { useQueryClient } from 'react-query';
5
6export const AXIOS_INSTANCE = Axios.create({ baseURL: '' });
7
8export const useCustomInstance = <T>(): ((
9  config: AxiosRequestConfig,
10) => Promise<T>) => {
11  const token = useToken(); // 做您想做的事
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
32export default useCustomInstance;
33
34export type ErrorType<Error> = AxiosError<Error>;

如果您使用 ES 模块（"type": "module"）。您也可以像这样提供一个钩子

示例：

1module.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};

生成的文件将使用 .js 扩展名导入 mutator。

类型：Boolean | Function。

默认值：true。

使用此属性禁用文件头的自动生成

您可以提供一个函数来自定义生成文件头的方式。您将接收规范的 info 对象作为参数，并应返回字符串数组。

1module.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};

属性键的命名约定

类型：Object。

更改为属性键生成的输出命名约定。

默认情况下，保留键的命名约定不变。

如果您要查找文件命名约定，请参见 namingConvention。

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

Enum

类型：String。

更改枚举键的命名约定。支持所有生成的枚举类型。

有效值：camelCase、PascalCase、snake_case、kebab-case。 与文件 namingConvention 相同。

fetch

类型：Object。

为生成的 fetch 客户端提供选项。

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

includeHttpResponseReturnType

类型：Boolean。默认值：true

当使用 fetch 作为 client 或 httpClient 时，fetch 响应类型包含 http 状态，以便应用程序更容易处理。如果您想返回定义的返回类型而不是自动生成的返回类型，请将此值设置为 false。

explode

类型：Boolean。默认值：true

默认情况下，fetch 客户端遵循 OpenAPI 规范的查询参数展开行为。这意味着查询参数将被展开，除非在 OpenAPI 模式中明确设置为 false。

如果您想保持与之前行为的向后兼容性（只有 explode: true 的参数才会被展开），可以将此值设置为 false。

jsonReviver

类型：String 或 Object

允许您在 fetch 客户端解析 JSON 时提供 reviver 函数。建议在设置 useDates 为 true 时使用此功能来恢复日期。

示例：

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

1// custom-reviver.ts
2const isoDateFormat =
3  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d*)?(?:[-+]\d{2}:?\d{2}|Z)?$/;
4
5export function customReviver(key: string, value: unknown) {
6  if (value && typeof value === 'string' && isoDateFormat.test(value)) {
7    return new Date(value);
8  }
9  return value;
10}

query

类型：Object。

为您提供覆盖生成的 query 的可能性

1module.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

类型：Boolean。

用于生成 useQuery 自定义钩子。如果未提供查询键，这是生成的默认钩子。

useMutation

类型：Boolean。

用于生成 useMutation 自定义钩子。只有当操作不是 GET 操作，且未配置生成 query 时，才会生成该钩子。

如果两者都配置了，operations override 将优先。

useInfinite

类型：Boolean。

用于生成 useInfiniteQuery 自定义钩子。

usePrefetch

类型：Boolean。

用于生成预取函数。这对于 NextJS SSR 或任何预取情况可能很有用。

生成函数示例：

1export 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

类型：String。

用于在使用 getFetchMore 函数时自动将 useInfiniteQuery 提供的查询参数添加到请求中。

options（已弃用，请使用 queryOptions）

类型：Object。

用于覆盖查询配置。可用选项请查看这里

queryKey

类型：String 或 Object。

有效值：queryKey 函数的路径或包含路径和名称的对象。

如果您提供对象，还可以添加 default 属性来使用导出默认函数。

示例：

1module.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

类型：String 或 Object。

有效值：queryOptions 函数的路径或包含路径和名称的对象。

如果您提供对象，还可以添加 default 属性来使用导出默认函数。

示例：

1module.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

类型：String 或 Object。

有效值：mutationOptions 函数的路径或包含路径和名称的对象。

如果您提供对象，还可以添加 default 属性来使用导出默认函数。

示例：

1module.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// custom-mutator-options.ts
4type OptionsWithMutationFn<
5  TData = unknown,
6  TError = Error,
7  TVariables = void,
8  TContext = unknown,
9> = UseMutationOptions<T, TError, TData, TContext> &
10  Required<Pick<UseMutationOptions<T, TError, TData, TContext>, 'mutationFn'>>;
11
12export const useCustomMutatorOptions = <
13  TData = unknown,
14  TError = Error,
15  TVariables = void,
16  TContext = unknown,
17>(
18  options: OptionsWithMutationFn<T, TError, TData, TContext>,
19): OptionsWithMutationFn<T, TError, TData, TContext> => {
20  const queryClient = useQueryClient();
21  if (options.mutationKey?.[0] === 'petDestroy') {
22    // 注意：`options.mutationKey?.[0]` 是无类型的。
23    options.onSuccess = (_data, variables, _context) => {
24      // 注意：`variables` 是无类型的。
25      options.onSuccess?.(data, variables, context);
26      // 注意：`queryKey` 是硬编码的，不能使用 `getGetPetQueryKey()`，因为这会引入循环依赖。
27      queryClient.invalidateQueries({
28        queryKey: ['api', 'v2', 'pet', variables.id],
29      });
30    };
31  }
32  // TODO: 为每个 mutation 添加更多 if 语句。
33  return options;
34};

signal

类型：Boolean。

用于移除 query 提供的中止信号的生成

shouldExportMutatorHooks

类型：Boolean。

默认值：true。

用于停止导出 mutator 钩子。如果您想完全依赖 useQuery、useSuspenseQuery 等，这很有用。

shouldExportQueryKey

类型：Boolean。

默认值：true。

用于停止导出查询键。

shouldSplitQueryKey

类型：Boolean。

默认值：false。

用于使 Orval 生成数组形式的查询键而不是字符串。

version

类型：number。

默认值：从 package json 检测。

用于为生成的钩子指定版本。如果您想强制为钩子指定版本，这很有用。

angular

类型：Object。

为 angular 客户端提供特定选项

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

provideIn

类型：Boolean 或 String。

有效值：true、false、'root'、'any'、''。

默认值：'root'。

可用于设置生成的 Angular 服务上的 providedIn 值。如果为 false，将不设置 providedIn。如果为 true 或未指定，将回退到默认值：root。

swr

类型：Object。

为生成的 swr 客户端提供选项。也可以扩展生成的函数。

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

useInfinite

类型：Boolean。

用于生成 useSWRInfinite 自定义钩子。

useSWRMutationForGet

类型：Boolean。

用于为 get 请求生成 useSWRMutation 自定义钩子。

示例：

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

swrOptions

类型：Object。

用于覆盖 useSwr 选项。可用选项请查看这里

示例：

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

swrMutationOptions

类型：Object。

用于覆盖 useSWRMutation 选项。可用选项请查看这里

示例：

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

swrInfiniteOptions

类型：Object。

用于覆盖 useSWRInfinite 选项。可用选项请查看这里

示例：

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

zod

类型：Object。

为 zod 客户端提供特定选项

1module.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

类型：Object。

默认值：false。

用于为 zod 模式设置严格模式。如果设置为 true，模式将以严格模式生成。

generate

类型：Object。

默认值：true。

用于设置要为 zod 模式生成哪种类型的模式。

示例：

1module.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};

在上面的示例中，排除响应体验证不会生成

coerce

类型：Object。

默认值：false。

用于为 zod 模式设置强制转换。如果设置为 true，模式将在可能的类型上生成强制转换。

您还可以提供强制转换类型数组，仅为指定类型生成强制转换类型。

示例：

1module.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

类型：Object。

用于向 zod 模式添加预处理函数。您可以使用自定义 mutator 在验证之前预处理数据。

示例：

1module.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

类型：Boolean。

为您提供为 OpenAPI 规范中 responses 字段中的所有 HTTP 状态生成模拟的可能性。默认情况下只生成 200 OK 响应。

1module.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:

1module.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 .

timeOptions

Type: Object.

Default Value: {}.

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

Example:

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

You can find more details in the zod documentation .

mock

类型：Object。

为您提供覆盖生成的模拟的可能性

properties

类型：Object 或 Function。

您可以使用此功能按属性覆盖生成的模拟。Properties 可以接受一个函数，该函数将规范作为参数并应返回一个对象或直接返回对象。此对象的每个键可以是正则表达式或要覆盖的属性的直接路径，值可以是返回所需值的函数或直接值。如果使用函数，这将在运行时执行。

1module.exports = {
2  petstore: {
3    output: {
4      override: {
5        mock: {
6          properties: {
7            '/tag|name/': 'jon', // 匹配每个名为 'tag' 或 'name' 的属性，包括嵌套的
8            '/.*.user.id/': faker.string.uuid(), // 匹配名为 'user' 的对象内名为 'id' 的每个属性，包括嵌套的
9            email: () => faker.internet.email(), // 仅匹配属性 'email'
10            'user.id': () => faker.string.uuid(), // 仅匹配完整路径 'user.id'
11          },
12        },
13      },
14    },
15  },
16};

format

类型：Object。

为您提供为 format 设置值的可能性。在您的规范中，如果您为属性设置 format: email，Orval 将自动为您生成随机电子邮件。默认可用格式请参见这里。

1module.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

类型：Boolean。

为您提供将每个属性设置为必需的可能性。

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

delay

类型：number、Function 或 false。

为您提供为模拟设置延迟时间的可能性。它可以是固定数字、false 或返回数字的函数。将 delay 设置为 false 会完全移除延迟调用。

默认值：1000

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

delayFunctionLazyExecute

类型：boolean。

为您提供将传递给 delay 的函数在运行时执行而不是在生成模拟时执行的可能性。

generateEachHttpStatus

类型：Boolean。

为您提供为 OpenAPI 规范中 responses 字段中的所有 HTTP 状态生成模拟的可能性。

arrayMin

类型：Number。

为指定多个项目的属性设置生成数组的默认最小长度。如果属性未定义 minItems，则使用此值。（默认为 1）

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

arrayMax

类型：Number。

为指定多个项目的属性设置生成数组的默认最大长度。如果属性未定义 maxItems，则使用此值。（默认为 10）

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

stringMin

类型：Number。

设置生成字符串的默认最小长度。如果属性未定义 minLength，则使用此值。（默认为 10）

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

stringMax

类型：Number。

设置生成字符串的默认最大长度。如果属性未定义 maxLength，则使用此值。（默认为 20）

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

numberMin

类型：Number。

设置生成数字的默认最小值。如果属性未定义 minimum，则使用此值。

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

numberMax

类型：Number。

设置生成数字的默认最大值。如果属性未定义 maximum，则使用此值。

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

fractionDigits

类型：Number。

设置浮点数中显示的小数位数。（默认为 2）

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

useExamples

全局模拟选项的扩展。如果设置为 true，模拟生成器将使用规范的 example 属性来生成模拟。如果未设置 example 属性，模拟生成器将回退到默认行为。将覆盖全局选项。

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

baseUrl

类型：String。

为您提供为模拟处理程序设置基础 url 的可能性。将覆盖全局选项。

hono

类型：Object

为您提供覆盖生成的 hono 的可能性

1module.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

类型：String。

您可以指定 hono 处理程序的输出路径。

示例：

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

然后将生成如下结构：

1src/
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

类型：String。

您可以更改验证器输出路径

compositeRoute

类型：String。

您可以输出一个定义复合路由的 hono 实例的文件。

示例：

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

然后将生成如下结构：

1src/
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

类型：Object。

为您提供覆盖模型的可能性

1module.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

类型：Object。

为您提供通过 operationId 覆盖生成的模拟的可能性。

对象的每个键应该是一个 operationId，并以对象作为值。

值对象可以采用与 override 属性相同的属性（mutator、query、transformer、mock）。

模拟选项还有一个可能性是 data 属性。它可以接受函数或直接值。函数将在运行时执行。

1module.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};

operationName

类型：Function。

1// 类型签名
2(operation: OperationObject, route: string, verb: Verbs) => string;

用于覆盖生成的操作名称的函数。

requestOptions

类型：Object | Boolean。

使用此属性为您的 http 客户端提供配置或完全从生成的文件中移除请求选项属性。

formData

类型：Boolean 或 String 或 Object。

有效值：formData 函数的路径或包含路径和名称的对象。您还可以定义如何处理关于数组的表单条目名称。

使用此属性在使用 multipart 时禁用表单数据的自动生成

如果您提供对象，还可以添加 default 属性来使用导出默认函数。

示例：

1module.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// 类型签名
2export const customFormDataFn = <Body>(body: Body): FormData => {
3  // 执行您的实现以将其转换为 FormData
4
5  return FormData;
6};

mutator

类型：String | Object

与直接在 formData 上定义 mutator 相同，但这样您也可以指定 arrayHandling。

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

arrayHandling

类型：serialize | serialize-with-brackets | explode

默认值：serialize

决定 FormData 生成如何处理数组。

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

对于以下所有示例，使用此规范：

1components:
2  schemas:
3    Pet:
4      type: object
5      properties:
6        name:
7          type: string
8        age:
9          type: number
10        relatives:
11          type: array
12          items:
13            type: object
14            properties:
15              name:
16                type: string
17              colors:
18                type: array
19                items:
20                  type: string
21                  enum:
22                    - white
23                    - black
24                    - green

类型 serialize 设置会生成以下代码：

1const formData = new FormData();
2if (pet.name !== undefined) {
3  formData.append(`name`, pet.name);
4}
5if (pet.age !== undefined) {
6  formData.append(`age`, pet.age.toString());
7}
8if (pet.relatives !== undefined) {
9  pet.relatives.forEach((value) =>
10    formData.append(`relatives`, JSON.stringify(value)),
11  );
12}

类型 serialize-with-brackets 设置会生成以下代码：

1const formData = new FormData();
2if (pet.name !== undefined) {
3  formData.append(`name`, pet.name);
4}
5if (pet.age !== undefined) {
6  formData.append(`age`, pet.age.toString());
7}
8if (pet.relatives !== undefined) {
9  pet.relatives.forEach((value) =>
10    formData.append(`relatives[]`, JSON.stringify(value)),
11  );
12}

类型 explode 设置会生成以下代码：

1const formData = new FormData();
2if (pet.name !== undefined) {
3  formData.append(`name`, pet.name);
4}
5if (pet.age !== undefined) {
6  formData.append(`age`, pet.age.toString());
7}
8if (pet.relatives !== undefined) {
9  pet.relatives.forEach((value, index) => {
10    if (value.name !== undefined) {
11      formData.append(`relatives[${index}].name`, value.name);
12    }
13    if (value.colors !== undefined) {
14      value.colors.forEach((value, index1) =>
15        formData.append(`relatives[${index}].colors[${index1}]`, value),
16      );
17    }
18  });
19}

formUrlEncoded

类型：Boolean 或 String 或 Object。

有效值：formUrlEncoded 函数的路径或包含路径和名称的对象。

使用此属性禁用表单 URL 编码的自动生成

如果您提供对象，还可以添加 default 属性来使用导出默认函数。

示例：

1module.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// 类型签名
2export const customFormUrlEncodedFn = <Body>(body: Body): URLSearchParams => {
3  // 执行您的实现以将其转换为 FormData
4
5  return URLSearchParams;
6};

paramsSerializer

类型：String 或 Object。

重要：这仅在使用 axios 或 angular 时有效。

有效值：paramsSerializer 函数的路径或包含路径和名称的对象。

使用此属性为所有使用查询参数的请求添加自定义参数序列化器。

如果您提供对象，还可以添加 default 属性来使用导出默认函数。

如果未指定，参数将按照 axios 默认方式序列化。

示例：

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

1// 类型签名
2export const customParamsSerializerFn = (
3  params: Record<string, any>,
4): string => {
5  // 执行您的实现以转换参数
6
7  return params;
8};

paramsSerializerOptions

类型：Object

重要：这仅在使用 axios 时有效。

使用此属性决定参数如何序列化。这仅在未定义 paramsSerializer 时考虑。目前，只有 qs 是可用选项。在这里了解更多关于 qs 及其设置的信息。

如果未指定，参数将按照 axios 默认方式序列化。

示例：

1module.exports = {
2  petstore: {
3    output: {
4      override: {
5        paramsSerializerOptions: {
6          qs: {
7            arrayFormat: 'repeat',
8          },
9        },
10      },
11    },
12  },
13};

useDates

类型：Boolean

有效值：true 或 false。默认为 false。

使用此属性将 OpenAPI date 或 datetime 转换为 JavaScript Date 对象而不是 string。

示例：

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

注意： 您必须提供 Axios 转换器来将这些转换为日期，因为这只是使 TypeScript 定义为 Date。您可以选择使用任何您想要的日期库，如 Moment、Luxon 或原生 JS 日期。

1// 类型签名
2const client = axios.create({
3  baseURL: '',
4});
5
6client.interceptors.response.use((originalResponse) => {
7  handleDates(originalResponse.data);
8  return originalResponse;
9});
10
11export default client;
12
13const isoDateFormat =
14  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d*)?(?:[-+]\d{2}:?\d{2}|Z)?$/;
15
16function isIsoDateString(value: any): boolean {
17  return value && typeof value === 'string' && isoDateFormat.test(value);
18}
19
20export 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); // 默认 JS 转换
28      // body[key] = parseISO(value); // date-fns 转换
29      // body[key] = luxon.DateTime.fromISO(value); // Luxon 转换
30      // body[key] = moment(value).toDate(); // Moment.js 转换
31    } else if (typeof value === 'object') {
32      handleDates(value);
33    }
34  }
35}

注意： 如果您使用 fetch 客户端并且 useDates 设置为 true，Date 类型的查询参数将使用 toISOString() 进行字符串化

useBigInt

类型：Boolean

有效值：true 或 false。默认为 false。

使用此属性将 OpenAPI int64 和 uint64 格式转换为 JavaScript BigInt 对象而不是 number。

示例：

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

coerceTypes

类型：Boolean

已弃用：请使用 zod.coerce 代替。

有效值：true 或 false。默认为 false。

使用此属性为 Zod 模式启用类型强制转换（仅适用于查询参数模式）。

如果您想使用 zod 模式在验证之前将（可能是字符串序列化的）查询参数强制转换为正确的类型，这很有用。

示例：

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

useNamedParameters

类型：Boolean。

默认值：false。

生成带有命名路径参数的操作接口，而不是为每个路径参数使用单独的参数。

示例：

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

useTypeOverInterfaces

类型：Boolean

有效值：true 或 false。默认为 false。

使用此属性使用 TypeScript type 而不是 interface。

示例：

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

useDeprecatedOperations

类型：Boolean

有效值：true 或 false。默认为 true。

使用此属性包含/排除生成在 OpenAPI 中标记为 "deprecated": true 的任何操作。

示例：

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

contentType

类型：Object

使用此属性包含或排除某些内容类型

示例：

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

useNativeEnums（已弃用，请使用 'enumGenerationType="enum"' 代替）

类型：Boolean

有效值：true 或 false。默认为 false。

使用此属性生成原生 TypeScript enum 而不是 type 和 const 组合。

示例：

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

enumGenerationType

类型：const | enum | union

默认值：const。

这用于指定如何生成枚举。const 生成常量对象，enum 生成原生枚举，union 生成简单的联合类型。要更改生成的枚举键的名称，您可以使用 x-enumNames 扩展您的 OpenAPI 模式。在这里了解更多。

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

当 enumGenerationType 为 const 时的结果：

1export type Example = (typeof Example)[keyof typeof Example];
2
3// eslint-disable-next-line @typescript-eslint/no-redeclare
4export const Example = {
5  foo: 'foo',
6  bar: 'bar',
7  baz: 'baz',
8} as const;

当 enumGenerationType 为 enum 时的结果：

1export enum Example {
2  foo = 'foo',
3  bar = 'bar',
4  baz = 'baz',
5}

当 enumGenerationType 为 union 时的结果：

export const Example = 'foo' | 'bar' | 'baz';

suppressReadonlyModifier

类型：Boolean

有效值：true 或 false。

默认值：false。

当在 OpenAPI 中指定 readonly 字段时，在从模式输出的 type 和 interface 字段中指定 readonly。

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

jsDoc

filter

类型：Object。

一个配置对象，允许您通过可选地提供一个将模式条目转换为键值对的过滤器函数来自定义 JSDoc 生成。

示例：

1module.exports = {
2  petstore: {
3    output: {
4      override: {
5        jsDoc: {
6          filter: (schema) => {
7            const allowlist = [
8              'type',
9              'format',
10              'maxLength',
11              'minLength',
12              'description',
13              'minimum',
14              'maximum',
15              'exclusiveMinimum',
16              'exclusiveMaximum',
17              'pattern',
18              'nullable',
19              'enum',
20            ];
21            return Object.entries(schema || {})
22              .filter(([key]) => allowlist.includes(key))
23              .map(([key, value]) => {
24                return {
25                  key,
26                  value,
27                };
28              })
29              .sort((a, b) => {
30                return a.key.length - b.key.length;
31              });
32          },
33        },
34      },
35    },
36  },
37};

输入：

1components:
2  schemas:
3    Pet:
4      type: object
5      required:
6        - id
7        - name
8      oneOf:
9        - $ref: '#/components/schemas/Dog'
10        - $ref: '#/components/schemas/Cat'
11      properties:
12        '@id':
13          type: string
14          format: iri-reference
15        id:
16          type: integer
17          format: int64
18        name:
19          type: string
20        tag:
21          type: string
22        email:
23          type: string
24          format: email
25        callingCode:
26          type: string
27          enum: ['+33', '+420', '+33'] # 故意重复的值
28        country:
29          type: string
30          enum: ["People's Republic of China", 'Uruguay']

结果：

1export interface Pet {
2  /**
3   * @type integer
4   * @format int64
5   */
6  id: number;
7  /**
8   * @type string
9   * @maxLength 0
10   * @minLength 40
11   * @description Name of pet
12   */
13  name: string;
14  /**
15   * @type integer
16   * @format int32
17   * @minimum 0
18   * @maximum 30
19   * @exclusiveMinimum true
20   * @exclusiveMaximum true
21   */
22  age?: number;
23  /**
24   * @type string
25   * @pattern ^\\d{3}-\\d{2}-\\d{4}$
26   * @nullable true
27   */
28  tag?: string | null;
29  /**
30   * @type string
31   * @format email
32   */
33  email?: string;
34  /**
35   * @type string
36   * @enum +33,+420,+33
37   */
38  callingCode?: PetCallingCode;
39  /**
40   * @type string
41   * @enum People's Republic of China,Uruguay
42   */
43  country?: PetCountry;
44}

allParamsOptional

类型：Boolean

有效值：true 或 false。

默认值：false。

适用于所有客户端，但可能只对 Tanstack Query 有意义。使用此属性使除路径参数外的所有参数都可选。这对于利用 Orval 的 Tanstack Query 自动启用功能很有用，请参见 https://github.com/orval-labs/orval/pull/894

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

urlEncodeParameters

类型：Boolean

有效值：true 或 false。默认为 false。注意： 目前仅适用于 Tanstack Query 客户端。

使用此属性启用路径/查询参数的 URL 编码。强烈推荐使用，将来可能会成为默认设置，请参见 https://github.com/orval-labs/orval/pull/895

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

optionsParamRequired

类型：Boolean

有效值：true 或 false。

默认值：false。使用此属性使第二个 options 参数成为必需的（例如使用自定义 axios 实例时）

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

propertySortOrder

类型：Alphabetical | Specification

默认值：Specification 这使您能够指定模型中属性的排序方式，可以按字母顺序排序或按它们在规范中出现的顺序排序。

1module.exports = {
2  petstore: {
3    output: {
4      propertySortOrder: 'Alphabetical',
5    },
6  },
7};

Was this page helpful?