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

@hey-api/openapi-ts并不是一个简单的“替换”，而是一次面向复杂需求的“升级”。它是一个功能更全面的现代化工具集，与专注生成类型的openapi-typescript定位不同。

🔎 核心差异一览

下面的表格可以清晰地展示这两个工具的核心区别：

🛠️ 不止这两个选择：聊聊其他替代方案

除了这两个，TypeScript 生态中还有其他优秀的工具：

• Orval：功能强大，尤其擅长生成与TanStack Query等框架深度集成的 API Hooks，如果你的项目重度使用 React Query，它是一个非常值得考虑的选择。

• Swagger Typescript API：老牌工具，能生成包含完整请求逻辑的 API 客户端代码，功能全面但学习曲线可能稍高。

• vika-cli：新兴工具，最大特点是快（使用 Rust 编写），不仅能生成类型和客户端，还能生成Zod校验模式。

• Kiota：微软官方出品，支持多语言，如果你的技术栈深度绑定微软生态，这是一个优势。

• tRPC：如果你能同时控制前后端，并且都使用 TypeScript，tRPC 能提供端到端的、无需代码生成的极致类型安全体验。

🤔 所以，我该怎么选？

你的选择取决于项目的具体需求和优先级：

1. 我只需要静态类型，追求极致轻量：
   选openapi-typescript。它完美地做到了“一件事并把它做好”，没有任何运行时负担，适合任何需要 API 类型定义的项目。

2. 我需要一套完整的解决方案，以提升团队效率：
   选@hey-api/openapi-ts。特别是当你的项目需要与Fetch/Axios客户端、TanStack Query等框架深度集成时，它能为你生成所有胶水代码，极大提升开发效率。

3. 我需要生成带有运行时校验的代码：
   可以关注vika-cli这类能同时生成类型和Zod校验模式的新兴工具。

4. 我追求端到端的极致类型安全，且能控制全栈：
   可以考虑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 枚举键名。这样一来，就实现了前后端枚举的解耦。

具体步骤如下：

1. 后端定义 (OpenAPI Spec)：在 Schema 中定义枚举值和对应的 TS 键名。

   yaml

   UserRole: type: string enum: - admin_user - regular_user x-enum-varnames: - ADMIN # 告诉生成器，admin_user 对应 TS 枚举键名 ADMIN - USER # 告诉生成器，regular_user 对应 TS 枚举键名 USER

2. 配置@hey-api/openapi-ts：在生成配置中，将enums.mode设置为typescript，让它生成真正的 TS 枚举而不是联合类型。

   javascript

   export default { input: 'path/to/openapi.yaml', output: 'src/client', plugins: ['@hey-api/sdk'], enums: { mode: 'typescript' // 生成真正的 TypeScript 枚举 } }

   这项功能在@hey-api/openapi-ts的较新版本中已得到支持。

3. 前端使用 (Generated Code)：最终生成的前端代码将是一个标准的 TS 枚举。

   typescript

   export 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 风格的青睐。

  javascript

  export default { // ...其他配置 enums: { mode: 'typescript.const' // 生成 as const 对象 } }

  根据你的项目风格，在enum和as const之间做选择。

🤔 如何抉择：两种方案的对比

为了方便你决策，我把两种核心解法再对比一下：

💎 总结

简单来说，你的问题归结为能否修改后端 OpenAPI 定义。

• 如果能修改，那么使用@hey-api/openapi-ts+x-enum-varnames的方案是最彻底、最专业的解法。

• 如果不能修改，那么使用@hey-api/openapi-ts的常量枚举模式或社区插件，是在现有约束下的最佳实践。

Vue3+Vite+TypeScript+axios的技术栈，最佳选择是哪个？

对于Vue3 + Vite + TypeScript + Axios这个技术栈，推荐的首选方案是orval。

orval凭借对Axios的深度集成和Vue Query的原生支持，几乎能开箱即用地满足你的所有技术栈需求。而@hey-api/openapi-ts虽然功能同样强大，但在这个特定组合下，需要更多配置才能达到同等的集成效果。

🛠️ 核心工具快速对比

为了让你更直观地了解，我准备了下面这个对比表格：

🏆 为什么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. 安装

在项目根目录下，使用你喜欢的包管理器安装orval：

bash

# 使用 pnpm pnpm add orval --save-dev # 或者使用 npm npm install orval --save-dev

2. 配置

在项目根目录创建orval.config.ts文件。这是一个基础配置示例，你可以根据项目需要调整：

typescript

import { 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中添加一个脚本命令：

json

"scripts": { "generate-api": "orval --config ./orval.config.ts" }

然后运行以下命令，即可生成完整的 TypeScript API 客户端：

bash

pnpm run generate-api # 或者 npm run generate-api

4. 在 Vue 组件中使用

生成的客户端可以直接在 Vue 组件中导入并使用，享受完整的类型提示和检查。

typescript

// 在 your-component.vue 中 <script setup lang="ts"> 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>