orval 生成 TypeScript API 客户端函数 createPets()：从 OpenAPI 规范到类型安全请求的完整实践

代码生成开发工具【免费下载链接】orvalorval is able to generate client with appropriate type-signatures (TypeScript) from any valid OpenAPI v3 or Swagger v2 specification, either in yaml or json formats. 项目地址https://gitcode.com/gh_mirrors/or/orval点击查看免费下载导读本文以 orval 项目samples/react-app示例中由 TypeDoc 生成的 createPets.md 文档为主体讲解 orval 如何基于 OpenAPI 规范中的POST /pets操作自动生成类型安全的createPets()客户端函数及其配套文档。读完本文你将掌握生成函数的签名含义与参数/返回值类型推导规则、docs文档输出选项的配置方式以及如何结合源码验证生成的 Axios 调用实现从而在自己项目中正确使用和追溯这类自动生成的 API 函数。一、文档从何而来orval 的 docs 文档生成链路createPets.md并非手写文档而是 orval 在生成客户端代码后通过 TypeDoc 与typedoc-plugin-markdown自动产出的 API 参考页。它的上级入口 docs-markdown/README.md 列出了本次文档集包含的接口Error、Pet、类型别名CreatePetsBody、CreatePetsResult等以及函数createPets、listPets、showPetById等createPets.md正是其中“函数”一节的单页明细。该链路在 orval 主包的 write-specs.ts 中实现当配置项output.docs存在时orval 动态导入typedoc与typedoc-plugin-markdown二者是可选 peer 依赖仅在需要生成文档时才安装见 write-specs.ts对已生成的.ts文件调用 TypeDoc 转换并输出到out指定目录最后再对文档目录统一执行formatter格式化。文档文件名createPets.md、文档内的Function: createPets()标题与参数表结构均由此链路自动生成。示例中触发这条链路的配置位于 orval.config.tspetstore-file-with-docs-markdown: { input: ./petstore.yaml, output: { target: src/api/endpoints/petstoreFromFileSpecWithDocsMarkdown.ts, formatter: prettier, docs: { out: ./docs-markdown, disableSources: true, }, }, },关键点说明docs.outTypeDoc 文档的输出目录即docs-markdown/docs.disableSources: true关闭文档中的源码引用链接因此createPets.md里不出现源文件跳转其余未配置的 TypeDoc 选项如theme默认取docs-markdown主题、readme默认none、logLevel默认None由 orval 在 write-specs.ts 中兜底设置同仓库还提供了docs的themeHTML 主题与plugin如typedoc-plugin-coverage两种扩展用法见 orval.config.ts 中的petstore-file-with-docs-html与petstore-file-with-docs-options-plugin两个示例项目。二、createPets() 函数签名逐项解读文档页正文给出的完整签名为createPets(createPetsBody, options?): PromiseAxiosResponsevoid, any, {}它对应生成的源码 petstoreFromFileSpecWithDocsMarkdown.ts/** * summary Create a pet */ export const createPets ( createPetsBody: CreatePetsBody, options?: AxiosRequestConfig, ): PromiseAxiosResponsevoid { return axios.post(/pets, createPetsBody, options); };参数 createPetsBody文档将其标注为CreatePetsBody类型别名其定义为object包含两个必填属性export type CreatePetsBody { name: string; tag: string; };该类型由 OpenAPI 规范的requestBody直接推导而来。在 petstore.yaml 中POST /pets的请求体声明了required: [name, tag]且name、tag均为string类型——这正是CreatePetsBody中两个属性均为必填string的依据。也就是说OpenAPI 中的 required 列表与属性类型会 1:1 映射为 TypeScript 类型约束调用方传入的对象若缺少name或tag、或类型不匹配将在编译期直接报错。可选参数 options?类型为AxiosRequestConfigany透传给底层 axios。它对应源码中options?: AxiosRequestConfig的参数声明最终被原样展开进axios.post(/pets, createPetsBody, options)调用。常用场景包括自定义请求头、超时时间、取消信号signal、onUploadProgress进度回调等——凡 axios 请求配置支持的能力都可经由该参数注入而不影响请求体的类型安全。返回值文档中的PromiseAxiosResponsevoid, any, {}表示一个异步请求承诺成功时兑现为 axios 的AxiosResponse其中响应体类型为void即201空响应。这一推导来自规范中POST /pets的201响应在 petstore.yaml 中201响应仅声明了description: Null response没有任何content因此 orval 将响应体推断为void并在源码中同时导出了便捷类型别名export type CreatePetsResult AxiosResponsevoid;见 petstoreFromFileSpecWithDocsMarkdown.ts。文档中AxiosResponsevoid, any, {}的any与{}是 TypeDoc 对AxiosResponse泛型默认参数D、T的展开表示分别对应响应头与额外元数据的默认类型实际使用中无需关注。三、签名背后的实现原理规范到代码的映射规则将createPets.md的签名与 petstore.yaml 对照可以总结出 orval 生成此类函数的通用映射规律OpenAPI 声明POST /pets生成的 TypeScript 产物对应文件operationId: createPets函数名createPetspetstoreFromFileSpecWithDocsMarkdown.ts路径/pets请求 URL 模板/pets同上requestBodyname、tag必填 string首个参数createPetsBody: CreatePetsBodyCreatePetsBody.mdHTTP 方法postaxios.post(...)调用同上201空响应无 content返回类型PromiseAxiosResponsevoid同上从源码结构还可以推断出 orval 的文档生成与代码生成共享同一套产物docs-markdown/functions/createPets.md与docs-markdown/functions/getCreatePetsUrl.md一一对应后者描述的是 orval 额外生成的 URL 辅助函数export const getCreatePetsUrl () { return axios .create({ baseURL: , params: null }) .getUri({ url: /pets, baseURL: }); };见 petstoreFromFileSpecWithDocsMarkdown.ts。该函数用于在不发起真实请求的情况下拼出/pets的完整 URL适合测试断言或需要在请求前获取地址的场景。另外示例中的 petstore 定义了pets标签与summary描述见 petstore.yaml它们会转化为生成代码顶部的 JSDoc 注释summary Create a pet——这也解释了为什么 TypeDoc 文档的标题页只展示函数签名而不包含 summary 正文TypeDoc 文档主体反映的是TypeScript 类型签名而 summary 等描述性信息保留在源码 JSDoc 中。四、实际使用与调用示例在samples/react-app中生成的函数可直接导入使用。一个典型的调用片段如下import { createPets, type CreatePetsResult } from ./api/endpoints/petstoreFromFileSpecWithDocsMarkdown; // 类型安全name/tag 缺一不可且必须为 string const response: CreatePetsResult await createPets({ name: Odie, tag: dog, }); // response.data 为 void201 空响应可按需读取 response.status console.log(response.status); // 201需要注意createPets的请求体类型CreatePetsBody是必填参数因为规范中requestBody.required: true若想表达可选请求体应在 OpenAPI 中将required去掉orval 会相应生成createPetsBody?: CreatePetsBody的可选参数形态示例配置未启用自定义 mutator因此该函数默认使用全局 axios 实例发送请求对比同一仓库中启用mutator的petstore项目其生成的函数会改由customInstance转发见 orval.config.ts若需要给该操作定制 mock可仿照listPets、showPetById在配置的override.operations中按operationId覆盖见 orval.config.ts。五、如何在其他项目中复现这套文档要在自己的 orval 项目中复现createPets.md这类函数文档步骤与前提如下安装依赖typedoc与typedoc-plugin-markdown需作为 devDependencies 安装否则 orval 会在日志中提示Install typedoc and typedoc-plugin-markdown to use the docs output option见 write-specs.ts在 orval 配置的output.docs中设置outMarkdown 输出目录可按需开启disableSources或传入theme、plugin、configPath等 TypeDoc 原生选项执行 orval 生成命令代码与文档会一并产出docs目录下的functions/*.md、interfaces/*.md、type-aliases/*.md即为逐函数、逐类型的参考页顶层README.md提供索引导航。总结createPets.md是 orval“规范 → 类型安全客户端 自动文档”全流程的一个缩影从 petstore.yaml 中的POST /pets操作出发orval 推导出请求体类型CreatePetsBody、空响应返回类型PromiseAxiosResponsevoid生成可直接调用的createPets()函数petstoreFromFileSpecWithDocsMarkdown.ts并通过 TypeDoc 输出可检索、可引用的单函数文档页。理解这条链路能帮助你快速定位生成代码的类型来源、按需调整 OpenAPI 声明并在文档缺失时从配置与源码中自行追溯生成逻辑。赞分享代码生成开发工具【免费下载链接】orvalorval is able to generate client with appropriate type-signatures (TypeScript) from any valid OpenAPI v3 or Swagger v2 specification, either in yaml or json formats. 项目地址https://gitcode.com/gh_mirrors/or/orval点击查看免费下载相关推荐Security-101 数据安全能力详解DLP、内部风险管理与数据保留三大工具体系Security 101 数据安全能力详解DLP、内部风险管理与数据保留三大工具体系 本文基于 Microsoft Security 101 课程Cyber代码生成开发工具告别命令行TortoiseGit让Git操作可视化零基础也能轻松上手告别命令行TortoiseGit让Git操作可视化零基础也能轻松上手 对于很多刚接触版本控制的开发者来说Git命令行常常让人望而生畏。繁杂的指令、晦涩的参桌面应用版本控制开发工具Orval终极指南从OpenAPI规范自动生成TypeScript客户端的完整教程Orval终极指南从OpenAPI规范自动生成TypeScript客户端的完整教程 Orval是一个功能强大的 RESTful客户端生成器 能够从任何有效的代码生成开发工具上一篇react-admin 响应式布局实战useMediaQuery 完整使用指南下一篇smooth-scroll核心原理剖析requestAnimationFrame与动画缓动函数详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考