OpenAPI TS工具对比：解决openapi-typescript生成的 联合类型 (Union Type)，无法直接对应 Java 后端枚举的问题

hey-api/openapi-ts并不是一个简单的“替换”而是一次面向复杂需求的“升级”。它是一个功能更全面的现代化工具集与专注生成类型的openapi-typescript定位不同。 核心差异一览下面的表格可以清晰地展示这两个工具的核心区别维度hey-api/openapi-tsopenapi-typescript定位一站式TypeScript 工具链生成类型、客户端、SDK 等。专注的类型生成器只生成 TypeScript 类型定义。核心产出SDK 客户端 类型定义 校验器等。纯类型定义文件 (.d.ts)。生态集成强内置 20 插件可集成 Fetch, Axios,TanStack Query等。弱通常需要配合openapi-fetch等额外工具使用。扩展性高通过插件系统灵活定制。中提供配置选项但扩展性有限。运行时开销有会生成包含业务逻辑的代码。零产出的纯类型定义不会增加包体积。社区与生态活跃的新兴工具被Vercel, PayPal等公司使用。成熟拥有更庞大的社区和丰富的文档。适用项目中大型、需要全链路类型安全和框架集成的项目。任何规模、追求极简轻量的项目或作为hey-api/openapi-ts的“组件”使用。前身是openapi-typescript-codegen的活跃分支。无。️ 不止这两个选择聊聊其他替代方案除了这两个TypeScript 生态中还有其他优秀的工具Orval功能强大尤其擅长生成与TanStack Query等框架深度集成的 API Hooks如果你的项目重度使用 React Query它是一个非常值得考虑的选择。Swagger Typescript API老牌工具能生成包含完整请求逻辑的 API 客户端代码功能全面但学习曲线可能稍高。vika-cli新兴工具最大特点是快使用 Rust 编写不仅能生成类型和客户端还能生成Zod校验模式。Kiota微软官方出品支持多语言如果你的技术栈深度绑定微软生态这是一个优势。tRPC如果你能同时控制前后端并且都使用 TypeScripttRPC 能提供端到端的、无需代码生成的极致类型安全体验。 所以我该怎么选你的选择取决于项目的具体需求和优先级我只需要静态类型追求极致轻量选openapi-typescript。它完美地做到了“一件事并把它做好”没有任何运行时负担适合任何需要 API 类型定义的项目。我需要一套完整的解决方案以提升团队效率选hey-api/openapi-ts。特别是当你的项目需要与Fetch/Axios客户端、TanStack Query等框架深度集成时它能为你生成所有胶水代码极大提升开发效率。我需要生成带有运行时校验的代码可以关注vika-cli这类能同时生成类型和Zod校验模式的新兴工具。我追求端到端的极致类型安全且能控制全栈可以考虑tRPC。它提供了一种不同于 REST 的范式能让你的 API 调用从前端到后端完全类型安全。 总结总的来说选择哪个工具本质上取决于你对“类型安全”的需求层次。openapi-typescript是解决“是什么类型”这一基础问题的利器。而hey-api/openapi-ts及其同类工具则是在此基础上进一步解决“如何用”和“如何更好地集成”的问题。希望这份对比能帮你找到最适合自己项目的工具但是openapi-typescript解决不了Java枚举和TypeScript枚举的问题呀你说得非常对这确实是openapi-typescript的一个核心痛点它生成的联合类型 (Union Type)无法直接对应 Java 后端的枚举特别是在命名和 IDE 智能提示方面存在短板。不过别担心这个问题有不止一种解法。hey-api/openapi-ts不仅解决了问题还提供了更灵活的选择。 你遇到的核心痛点命名映射的缺失openapi-typescript默认生成的代码是纯静态的联合类型如type Status APPROVED | REJECTED。这可以保证类型安全但丢失了枚举的常量名。当后端 Java 枚举的字符串值如Approved Request包含空格等特殊字符时openapi-typescript在生成时会将其统一替换为下划线_这会破坏代码的可读性和映射关系。 解法一用hey-api/openapi-ts和扩展字段生成 TS 枚举hey-api/openapi-ts配合 OpenAPI 的x-enum-varnames扩展字段是解决命名映射问题的最直接方案。它的核心思路是在后端 OpenAPI 定义中通过x-enum-varnames字段明确告知生成器前端期望的 TypeScript 枚举键名。这样一来就实现了前后端枚举的解耦。具体步骤如下后端定义 (OpenAPI Spec)在 Schema 中定义枚举值和对应的 TS 键名。yamlUserRole: type: string enum: - admin_user - regular_user x-enum-varnames: - ADMIN # 告诉生成器admin_user 对应 TS 枚举键名 ADMIN - USER # 告诉生成器regular_user 对应 TS 枚举键名 USER配置hey-api/openapi-ts在生成配置中将enums.mode设置为typescript让它生成真正的 TS 枚举而不是联合类型。javascriptexport default { input: path/to/openapi.yaml, output: src/client, plugins: [hey-api/sdk], enums: { mode: typescript // 生成真正的 TypeScript 枚举 } }这项功能在hey-api/openapi-ts的较新版本中已得到支持。前端使用 (Generated Code)最终生成的前端代码将是一个标准的 TS 枚举。typescriptexport enum UserRole { ADMIN admin_user, USER regular_user }⚙️ 解法二用插件或直接生成常量枚举如果不想在 OpenAPI 文件中添加扩展字段或者想探索其他方式可以尝试以下两种路径。路径一使用openapi-typescript的生态插件可以试试openapi-typescript-infra/openapi-typescript-enum这个社区插件。它能作为openapi-typescript的一个替代命令运行将原来生成的联合类型替换为真正的enum对象。路径二使用hey-api/openapi-ts生成常量枚举hey-api/openapi-ts也提供了灵活的配置。将enums.mode设置为typescript.const就能生成一个as const断言的对象这在某些场景下可能比enum更轻量也更受现代 TS 风格的青睐。javascriptexport default { // ...其他配置 enums: { mode: typescript.const // 生成 as const 对象 } }根据你的项目风格在enum和as const之间做选择。 如何抉择两种方案的对比为了方便你决策我把两种核心解法再对比一下对比维度方案一x-enum-varnames映射方案二插件/常量枚举灵活性高可在 OpenAPI 层精确控制命名与后端 Java 枚举值完全解耦。中无法自定义命名只能使用枚举的原始值作为键名。集成成本中需要修改后端 OpenAPI 文件且需生成工具支持hey-api/openapi-ts等支持。低前端即可完成配置无需后端配合。适用场景对类型命名有严格要求追求前后端枚举完美映射的大中型项目。快速原型开发或对前端枚举命名没有特殊要求的项目。 总结简单来说你的问题归结为能否修改后端 OpenAPI 定义。如果能修改那么使用hey-api/openapi-tsx-enum-varnames的方案是最彻底、最专业的解法。如果不能修改那么使用hey-api/openapi-ts的常量枚举模式或社区插件是在现有约束下的最佳实践。Vue3ViteTypeScriptaxios的技术栈最佳选择是哪个对于Vue3 Vite TypeScript Axios这个技术栈推荐的首选方案是orval。orval凭借对Axios的深度集成和Vue Query的原生支持几乎能开箱即用地满足你的所有技术栈需求。而hey-api/openapi-ts虽然功能同样强大但在这个特定组合下需要更多配置才能达到同等的集成效果。️ 核心工具快速对比为了让你更直观地了解我准备了下面这个对比表格特性orval(首推)hey-api/openapi-tsopenapi-typescript定位一站式API客户端生成器开箱即用模块化的代码生成工具链高度可定制轻量级类型生成器只做一件事Axios 集成原生支持配置简单支持但需要额外安装hey-api/client-axios插件不涉及仅生成类型需自己用Axios请求Vue 集成原生支持vue-query可直接生成useQuery等组合式函数需额外配置tanstack/vue-query插件不涉及Vite 性能标准Node.js工具生成速度适中标准Node.js工具生成速度适中极快纯类型生成无运行时开销枚举处理支持生成真正的TS枚举符合预期支持但需配合x-enum-varnames等额外配置不支持默认转为联合类型处理不规范值可能出错生态成熟度成熟社区活跃新兴增长迅速已被Vercel、PayPal等采用非常成熟广泛应用 为什么orval是你的技术栈最佳选择对于你选择的Vue3 Vite TypeScript Axios技术组合orval几乎是为它量身定做的与你技术栈的无缝集成orval原生支持axios能直接生成你需要的请求代码。同时它也能为vue-query生成对应的组合式函数Composables帮你轻松实现服务端状态管理与 Vue 3 的生态完美契合。出色的枚举处理orval能直接将 OpenAPI 中的枚举生成标准的 TypeScriptenum彻底解决你之前遇到的枚举问题无需任何额外配置。配置简单上手快orval的目标是开箱即用。你只需要一个简单的配置文件就能直接生成完整的、类型安全的 API 客户端代码。 为什么不首选另外两个hey-api/openapi-ts它的理念更偏向于提供一个灵活的“工具集”而非“开箱即用”的方案。要让它完美适配你的技术栈需要进行更多配置和组合。例如你需要自行组合hey-api/client-axios和tanstack/vue-query等插件这在一定程度上增加了上手成本。openapi-typescript它的定位非常专一就是“生成类型”。它本身不会为你生成任何请求客户端代码你需要自己编写 Axios 请求逻辑并手动引入它生成的类型。因此它虽然零运行时开销但无法提供像orval那样一站式的便利。它也更适合与其他工具如openapi-fetch搭配而这又会引入新的学习成本。 快速上手指南使用orval在你的 Vue3 Vite 项目中集成orval非常简单只需几步1. 安装在项目根目录下使用你喜欢的包管理器安装orvalbash# 使用 pnpm pnpm add orval --save-dev # 或者使用 npm npm install orval --save-dev2. 配置在项目根目录创建orval.config.ts文件。这是一个基础配置示例你可以根据项目需要调整typescriptimport { defineConfig } from orval; export default defineConfig({ your-api: { // 一个自定义的配置名称 input: { target: http://localhost:8080/api-docs/openapi.json, // 你的OpenAPI规范URL }, output: { mode: split, // 推荐使用 split 模式将服务和模型分开生成 target: ./src/api/client.ts, // 生成的客户端文件路径 schemas: ./src/api/models, // 生成的TypeScript模型路径 client: axios, // 指定使用axios客户端 baseUrl: /api, // 你的API基础路径 clean: true, // 生成前清理输出目录 }, hooks: { afterAllFilesWrite: prettier --write, // 可选生成后自动格式化代码 }, }, });3. 生成在package.json中添加一个脚本命令jsonscripts: { generate-api: orval --config ./orval.config.ts }然后运行以下命令即可生成完整的 TypeScript API 客户端bashpnpm run generate-api # 或者 npm run generate-api4. 在 Vue 组件中使用生成的客户端可以直接在 Vue 组件中导入并使用享受完整的类型提示和检查。typescript// 在 your-component.vue 中 script setup langts import { useGetUsers } from /api/client; // 自动生成的组合式函数 // 或者直接调用API函数 // import { usersControllerGetUsers } from /api/client; // 使用 Vue Query 钩子 const { data, isLoading, error } useGetUsers(); // 也可以直接调用API函数 // const fetchUsers async () { // const response await usersControllerGetUsers(); // console.log(response.data); // }; /script