Vue3+Vite+TS技术栈，API生成工具(vite-plugin-openapi-ts/Orval/@hey-api/openapi-typescript-codegenscript)

从后端的 OpenAPI 文档生成类型安全的 API 客户端针对你使用的 Vue 3 Vite TypeScript 技术栈目前最主流的工具有三个它们都能从后端的 OpenAPI 文档生成类型安全的 API 客户端。这里是三者的快速对比工具一句话总结适合场景hey-api/openapi-ts(原openapi-typescript-codegen)生态最健全的官方解决方案由 Vercel 维护生成代码可靠。绝大多数项目特别是对稳定性和长期维护有要求的项目。Orval功能最全的瑞士军刀无缝集成 Vue Query生成状态管理逻辑。需要高级数据同步和缓存功能希望为 Vue 3 应用引入 Vue Query 的场景。vite-plugin-openapi-ts原生 Vite 体验作为插件集成开发时自动更新。追求极致的开发效率希望 API 客户端能随开发自动同步的 Vite 项目。 推荐选择hey-api/openapi-ts它由 Vercel 团队维护是目前最主流、生态最健全的选择可靠性高。而且openapi-typescript生成的类型还能与它无缝配合。下面是用它生成请求客户端的步骤1. 安装bashnpm install hey-api/openapi-ts --save-dev2. 配置vite.config.tstsimport { defineConfig } from vite import vue from vitejs/plugin-vue import { VitePlugin as OpenAPI } from hey-api/vite-plugin export default defineConfig({ plugins: [ vue(), OpenAPI({ input: http://localhost:8080/v3/api-docs, // 你的后端文档地址 output: src/api/generated, // 生成代码的存放路径 client: hey-api/client-fetch, // 生成的客户端类型也可选 axios }), ], })3. 开发时使用ts// 在组件或 API 模块中 import { client, getCapitalAdjustments } from /api/generated // 设置全局请求配置如基础URL、拦截器等 client.setConfig({ baseUrl: /api, // 你的代理路径 }) async function fetchData() { // 调用生成的API函数参数和返回值都有完整类型提示 const { data, error } await getCapitalAdjustments({ keyword: , current: 1, size: 20, }) }配置好之后API 客户端会在开发和构建时自动生成前后端类型会始终保持同步。️ 其他方案配置参考如果想了解更多其他方案可以参考这些配置示例details summary bOrval Vue Query 配置/b/summary如果你想为 Vue 3 应用引入 Vue Query 来管理服务端状态Orval 是绝配。安装bashnpm install -D orval配置 (orval.config.js):jsimport { defineConfig } from orval export default defineConfig({ your-api: { input: http://localhost:8080/v3/api-docs, output: { mode: split, target: src/api/orval/client.ts, schemas: src/api/orval/models, client: vue-query, // 关键生成 Vue Query 的 composables baseUrl: /api, }, }, })使用vuescript setup langts import { useGetCapitalAdjustments } from /api/orval/client const { data, isLoading, error } useGetCapitalAdjustments({ keyword: , current: 1, size: 20, }) /script/detailsdetails summary bvite-plugin-openapi-ts 配置/b/summary这个插件提供更原生 Vite 的集成体验可以自动生成并持续更新客户端代码。安装bashnpm install -D vite-plugin-openapi-ts配置 (vite.config.ts):tsimport { defineConfig } from vite import vue from vitejs/plugin-vue import OpenapiTs from vite-plugin-openapi-ts export default defineConfig({ plugins: [ vue(), OpenapiTs({ input: http://localhost:8080/v3/api-docs, output: src/api/generated, }), ], })/detailsdetails summary bswagger-typescript-api 配置/b/summary如果你的项目已经有一些现成的脚本也可以考虑这个工具。安装bashnpm install -D swagger-typescript-api添加 npm 脚本 (package.json):jsonscripts: { gen:api: swagger-typescript-api -p http://localhost:8080/v3/api-docs -o ./src/api -n myApi.ts }/details 总结与建议想稳定、不折腾直接选择hey-api/openapi-ts它能满足大部分需求且有官方团队保障。希望最大化开发效率可以尝试vite-plugin-openapi-ts体验 Vite 插件带来的自动更新特性。追求高级功能如果你的项目需要处理复杂的服务端状态Orval与 Vue Query 的组合将提供强大的支持。这几种工具都能极大地提升开发体验。结合你的项目现状目前的当务之急是在后端添加一个简单的 Dummy Controller让 OpenAPI 能生成正确的 Schema 定义。前端使用Vue3ViteTypeScriptaxios为你的 Vue 3 Vite TypeScript Axios 项目选择 API 生成工具主要看你对开发体验和项目长期维护性的要求。这里为你梳理了几个主流方案你可以根据自己的偏好来选择。⚙️ 几种主流方案对比工具核心特点优点缺点适用场景vite-plugin-openapi-tsVite 插件启动/构建时自动生成使用方式最简洁零配置框架无关生成带拦截器的通用客户端与axios等库无缝集成需要对生成工具本身有基本的了解追求高效开发希望在开发时几乎无感知地获得类型安全的 API 客户端hey-api/openapi-ts功能强大且灵活官方支持 Axios 客户端生成可深度定制生态完善支持生成 Axios、Fetch 等多种客户端可定制性强配置相对其他方案稍复杂一些需要高级配置如自定义请求实例、运行时配置等Orval功能全面的“瑞士军刀”能生成针对特定框架如 Vue Query的 Hooks不仅能生成 Axios 客户端还能与 Vue Query 深度集成提供缓存、状态管理等功能生成的代码量较大学习曲线稍陡项目需要集成服务端状态管理追求极致的开发体验swagger-typescript-api简单直接的命令行工具专为生成 Axios 客户端设计配置简单通过一条命令即可生成易于集成到现有工作流功能相对单一主要聚焦于客户端代码生成习惯使用命令行希望快速生成基础 API 客户端代码 推荐方案vite-plugin-openapi-ts如果你希望以最小的成本获得最流畅的开发体验那么vite-plugin-openapi-ts是当前技术栈下的最优解。它将类型生成无缝集成到 Vite 的构建流程中几乎不需要手动维护。1. 安装依赖在你的项目根目录下执行bashnpm install -D vite-plugin-openapi-ts # 或 pnpm add -D vite-plugin-openapi-ts # 或 yarn add -D vite-plugin-openapi-ts该插件是开发依赖不会增加生产环境的代码体积。2. 配置 Vite打开vite.config.ts文件引入插件并配置 OpenAPI 文档地址typescript// vite.config.ts import { defineConfig } from vite import vue from vitejs/plugin-vue import openapiPlugin from vite-plugin-openapi-ts export default defineConfig({ plugins: [ vue(), openapiPlugin({ url: http://localhost:8080/v3/api-docs, // 你的后端OpenAPI文档地址 // baseUrl: http://localhost:8080, // 可选API基础地址 // outputDir: src/openapi, // 可选生成代码的输出目录默认为 src/openapi }), ], })它是如何工作的配置好后当你运行npm run dev启动开发服务器或执行npm run build构建项目时这个插件就会自动拉取最新的 OpenAPI 规范并生成对应的 TypeScript 代码。当你修改了 API 文档后端更新接口后只需重启开发服务器新的类型和客户端代码就会自动生成。3. 在组件中使用插件会在你配置的outputDir默认为src/openapi目录下生成文件。你可以这样在你的 Vue 组件中调用vuescript setup langts // 导入生成的 API 客户端 import apiClient from /openapi; // 定义组件逻辑 async function fetchCapitalList() { try { // 调用 /capital/adjustments/query 接口路径、方法、参数、返回值都有完整的类型提示 const { data } await apiClient( /capital/adjustments/query, post, { body: { keyword: , current: 1, size: 20 } } ); console.log(API 返回的数据是:, data); } catch (error) { console.error(请求失败:, error); } } /scriptapiClient的使用方式非常直观它接受(path, method, options)三个参数其中path和method都会受到 TypeScript 的严格检查任何拼写错误都会在编译时被捕获。4. 进阶配置统一设置与拦截器你可以在应用的入口文件如main.ts中对生成的客户端进行全局配置typescript// main.ts import { createApp } from vue import App from ./App.vue import apiClient, { config, interceptors } from /openapi // 设置全局基础URL和请求头 config.baseUrl /api; config.headers { Authorization: Bearer ${localStorage.getItem(token)} }; // 添加请求拦截器 interceptors.request.use((config) { console.log(请求发送前:, config.url); return config; }); // 添加响应拦截器 interceptors.response.use((response) { console.log(收到响应:, response.status); return response; }); createApp(App).mount(#app)这样所有通过apiClient发出的请求都会自动应用这些全局配置和拦截器逻辑非常方便。 备选方案hey-api/openapi-ts需要更多配置如果你希望拥有更高的灵活性或者未来有定制客户端的需要hey-api/openapi-ts是一个非常强大的选择它提供了对 Axios 客户端的官方支持。安装npm install -D hey-api/openapi-ts。配置创建一个openapi-ts.config.ts配置文件指定输入和输出并在plugins中明确使用hey-api/client-axios。生成运行npx hey-api/openapi-ts命令即可生成。使用在项目中导入生成的client并进行配置和使用。这种方式将生成过程更多地交给开发者控制适合对自动化流程有特殊需求的场景。 总结你的技术栈Vue 3 Vite TypeScript Axios与vite-plugin-openapi-ts这个方案是绝配。它的自动化程度很高几乎无需额外操作就能为你的项目带来完整的类型安全。你可以先尝试这个方案如果未来有更复杂的需求再考虑迁移到hey-api/openapi-ts。 核心结论vite-plugin-openapi-ts自身已集成了类型和客户端生成能力它是一个完整的“一站式”解决方案。一旦你决定使用它就不再需要单独安装或配置openapi-typescript。 它们的分工与关系为了让你更清楚地理解可以把它俩的关系看成是“集成方案”与“底层工具”的关系vite-plugin-openapi-ts集成方案它是一个面向 Vite 的“开箱即用”插件能根据你的 OpenAPI 文档自动生成完整的 TypeScript 类型定义和可直接调用的 API 客户端。它内置了所需的所有功能旨在提供一站式的开发体验。openapi-typescript底层工具它只是一个专注于生成.d.ts类型声明文件的“单一功能”库。它不负责生成可执行的请求函数需要你配合其他工具如openapi-fetch来使用。核心区别vite-plugin-openapi-ts的功能覆盖了openapi-typescript并在此基础上增加了生成完整 API 客户端的核心能力。 功能对比一览功能点vite-plugin-openapi-tsopenapi-typescript生成 TypeScript 类型✅ 可以✅ 可以核心功能生成 API 客户端代码✅ 可以内置❌ 不可以需配合openapi-fetch在 Vite 开发/构建时自动更新✅ 可以插件方式❌ 不可以需手动运行 CLI通过命令行CLI使用✅ 可以内置✅ 可以提供请求/响应拦截器✅ 可以❌ 不可以提供全局配置✅ 可以❌ 不可以与 Vue 3 等技术栈的集成方式作为 Vite 插件无缝集成需要手动配置工作流✅ 总结你只需要安装并配置vite-plugin-openapi-ts即可。它会自动完成类型生成和客户端创建的所有工作。如果未来有其他非 Vite 项目需要生成类型那时可以考虑单独使用openapi-typescript。