vite-plugin-openapi-ts 安装、配置、卸载、介绍

安装npm install -D vite-plugin-openapi-ts配置vite.config.ts// 引入插件 vite-plugin-openapi-ts import openapiPlugin from vite-plugin-openapi-ts; // https://vitejs.dev/config/ export default defineConfig({ // 插件配置 plugins: [ openapiPlugin({ // 后端 OpenAPI 文档地址 url: http://localhost:8080/v3/api-docs, // API基础地址可选默认为 http://localhost:8080 // baseUrl: http://localhost:8080, // 生成代码的输出目录可选默认为 src/openapi outputDir: src/openapi }) ],整个文件完整代码import { fileURLToPath, URL } from node:url; import { defineConfig } from vite; import vue from vitejs/plugin-vue; // 引入插件 vite-plugin-vue-setup-extend.vue 文件中script 标签中就可以使用 name 属性如script setup langts nameLogin import VueSetupExtend from vite-plugin-vue-setup-extend; // 引入插件 vite-plugin-externals 的 viteExternalsPlugin import { viteExternalsPlugin } from vite-plugin-externals; // 引入插件 vite-plugin-vue-devtools import VueDevTools from vite-plugin-vue-devtools; // 引入插件 vite-plugin-openapi-ts import openapiPlugin from vite-plugin-openapi-ts; // https://vitejs.dev/config/ export default defineConfig({ // 插件配置 plugins: [ vue(), VueSetupExtend(), // 配置此插件以全局注入 jQuery viteExternalsPlugin({ // 将 import 的 jquery 替换为全局的 jQuery 变量 jquery: jQuery }), VueDevTools(), openapiPlugin({ // 后端 OpenAPI 文档地址 url: http://localhost:8080/v3/api-docs, // API基础地址可选默认为 http://localhost:8080 // baseUrl: http://localhost:8080, // 生成代码的输出目录可选默认为 src/openapi outputDir: src/openapi }) ], // 解析配置 resolve: { // 设置路径别名 alias: { // new URL(./src, import.meta.url) 创建从当前文件到 ./src 目录的绝对URL // fileURLToPath() 将 URL 转换为文件系统路径 // 作为别名指向 src 目录的绝对路径 : fileURLToPath(new URL(./src, import.meta.url)), api: fileURLToPath(new URL(./src/api, import.meta.url)), assets: fileURLToPath(new URL(./src/assets, import.meta.url)), components: fileURLToPath(new URL(./src/components, import.meta.url)), hooks: fileURLToPath(new URL(./src/hooks, import.meta.url)), router: fileURLToPath(new URL(./src/router, import.meta.url)), stores: fileURLToPath(new URL(./src/stores, import.meta.url)), types: fileURLToPath(new URL(./src/types, import.meta.url)), utils: fileURLToPath(new URL(./src/utils, import.meta.url)), views: fileURLToPath(new URL(./src/views, import.meta.url)) } }, // 服务配置 server: { // 指定端口vite默认 5173 port: 5173, // 指定服务器监听的 IP 地址如果将此设置为 0.0.0.0 或者 true 将监听所有地址 host: 0.0.0.0, // 代理设置 proxy: { // 【代理1】获取路径中包含有 /api 的请求 /api: { // 后台服务所在的源 target: http://localhost:8080, // 修改源 changeOrigin: true, // 将 api 替换为 如/api/account/login - /account/login最终代理访问的 URL 为 http://localhost:8080/account/login rewrite: (path) path.replace(/^\/api/, ) }, // 【代理2】获取路径中包含有 /apu 的请求【上传数据】用于前端网面对外请求发送数据 /apu: { // 后台服务所在的源 target: http://localhost:8081, // 修改源 changeOrigin: true, // 将 apu 替换为 如/apu/sampleItemResult/upload - /sampleItemResult/upload最终代理访问的 URL 为 http://localhost:8081/sampleItemResult/upload rewrite: (path) path.replace(/^\/apu/, ) }, // 【代理3】获取路径中包含有 /ws 的请求WebSocket双向通信专用路径 /ws: { // 后台服务所在的源 target: http://localhost:8080, // 修改源 changeOrigin: true, ws: true // 重要启用 WebSocket 代理 } } } });卸载npm uninstall vite-plugin-openapi-ts介绍vite-plugin-openapi-ts是一个Vite插件它直接将后端的OpenAPI也常被称为Swagger规范文档自动转化为你前端项目中可直接调用的、类型安全的API客户端。 核心机制如何实现自动化它的核心机制是完全自动化的配置在vite.config.ts中配置好OpenAPI文档地址插件会立即在开发服务器npm run dev启动时读取并解析该文档。生成根据文档内容在src/openapi/目录下生成两个文件schemes.ts包含所有数据模型如CapitalUseResponse的 TypeScript 类型。index.ts包含一个名为apiClient的、完全类型安全的请求客户端。消费在你的Vue组件中直接使用apiClient发起请求享受完整的代码提示和类型校验。同步当后端API文档更新时前端开发服务器在重启或重载后会自动重新生成最新的客户端代码。✅ 核心优势与潜在局限优势自动化通过将API客户端生成集成到构建流程中解决了手工维护带来的不一致和效率问题。类型安全生成的客户端能为请求参数、响应数据提供完整的类型提示和校验能有效避免因接口变动而导致的运行时错误。可定制生成的客户端支持修改全局配置和添加拦截器可以灵活适配项目需求。灵活性除了作为Vite插件它也提供了命令行工具CLI可以在CI/CD等独立场景下运行。潜在局限与注意事项强依赖严格依赖OpenAPI文档的准确性和完整性。文档不规范会直接影响生成代码的可用性。工作流变更引入后团队需要适应新的API调用方式原有的手工封装和类型维护工作可以逐步淘汰。生成代码体积为一个大型API生成完整的客户端代码会占用一些项目空间但通常可以忽略不计。框架锁定虽然它宣称框架无关但其自动生成和Vite启动的强绑定意味着它主要适用于Vite项目。 与openapi-typescript的对比我们可以通过一个表格来更直观地对比vite-plugin-openapi-ts和openapi-typescript帮助你理解它们的核心区别特性vite-plugin-openapi-tsopenapi-typescript核心定位自动化客户端生成轻量级类型生成输出内容类型定义(.ts) API客户端函数仅类型定义(.d.ts)使用方式直接调用生成的apiClient配合openapi-fetch或手动封装fetch/axios对文档完整性高。缺失会导致生成失败或类型错误较低。缺失部分会推断为unknown与现有代码集成侵入性高。需改用新的调用方式侵入性低。类型可直接用于现有代码最佳场景新项目或愿意重构API层的项目现有项目渐进式迁移或轻量级使用简单来说vite-plugin-openapi-ts提供的是“开箱即用”的完整解决方案而openapi-typescript更像一个可灵活嵌入的“构建块”。 实践指南快速上手1. 安装bashnpm install -D vite-plugin-openapi-ts # 或 yarn add -D vite-plugin-openapi-ts # 或 pnpm add -D vite-plugin-openapi-ts2. 配置插件在vite.config.ts中配置插件并确保后端的OpenAPI文档服务SpringDoc是已启动状态。typescriptimport { 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, outputDir: src/openapi, }), ], });3. 调用生成的客户端在你的Vue组件或TS文件中直接调用生成的apiClient。typescriptimport apiClient from /openapi; async function queryCapitalAdjustPage() { const { data } await apiClient(/capital/adjustments/query, post, { body: { current: 1, size: 20 } }); console.log(data); }apiClient会自动完成HTTP请求其path、method和参数结构都受到TypeScript的严格保护任何不匹配都会在编译时暴露出来。⚙️ 高级特性对接你的Axios实例生成的apiClient默认使用fetch。要让它使用你项目中已有的axios实例你需要借助其背后更底层的工具hey-api/openapi-ts。可以参考以下配置示例在项目根目录创建openapi-ts.config.ts文件通过client选项指定为hey-api/client-axios。typescript// openapi-ts.config.ts import { defineConfig } from hey-api/openapi-ts; export default defineConfig({ client: hey-api/client-axios, input: http://localhost:8080/v3/api-docs, output: src/openapi, });然后在vite.config.ts中引入该配置。typescript// vite.config.ts import { defineConfig } from vite; import vue from vitejs/plugin-vue; import openapi from vite-plugin-openapi-ts; export default defineConfig({ plugins: [ vue(), openapi({ // 这里的配置会继承你在 openapi-ts.config.ts 中的设置 }), ], });这样生成的apiClient就会基于axios发送请求。 基于文件的工作流除了依赖Vite启动该插件还提供了独立的命令行工具方便你将代码生成集成到CI/CD等独立流程中。创建配置文件在项目根目录创建openapi.config.json。json{ url: http://localhost:8080/v3/api-docs, outputDir: src/openapi }添加NPM脚本在package.json中添加命令。json{ scripts: { generate-api: openapi-ts generate, clean-api: openapi-ts clean } } 总结vite-plugin-openapi-ts是一个“自动化API客户端生成器”。它的核心价值在于“自动化”和“类型安全”能显著提升开发效率与代码质量。对OpenAPI文档的完整性要求较高。如果你的项目Vite构建流程成熟后端API文档稳定规范追求极致的自动化开发体验vite-plugin-openapi-ts是一个值得考虑的先进方案。如果你更倾向于逐步引入类型或后端文档尚不稳定希望能更灵活地集成到现有代码中那么之前推荐的openapi-typescript方案会是更稳妥的选择。