OpenAPI转TypeScript类型：@hey-api/openapi-ts的枚举处理优势

1. 项目背景与痛点解析

在前后端分离的开发模式中，OpenAPI规范已成为定义API接口的事实标准。而TypeScript作为前端主流开发语言，如何将OpenAPI规范准确转换为TS类型定义，一直是工程实践中的关键环节。openapi-typescript作为早期解决方案，在处理Java枚举类型时存在明显缺陷——生成的联合类型无法与Java枚举完美对应，导致类型系统失去精确性。

典型问题场景：当后端定义的枚举值为数字（如100/200/300）时，openapi-typescript会生成简单的数字联合类型（100 | 200 | 300），而丢失了Java枚举中精心设计的语义化命名（如Unauthorized/AccessDenied）。这不仅降低了代码可读性，也使IDE智能提示失去价值。

2. @hey-api/openapi-ts核心优势

2.1 枚举处理的革命性改进

该工具通过解析OpenAPI扩展字段（x-enum-varnames/x-enum-descriptions），将枯燥的数字枚举转换为具有完整语义的TS枚举类型。对比原始方案：

typescript复制// openapi-typescript输出
type ErrorCode = 100 | 200 | 300;

// @hey-api/openapi-ts输出
enum ErrorCode {
  /** User is not authorized */
  Unauthorized = 100,
  /** User has no access */
  AccessDenied = 200, 
  /** Something went wrong */
  Unknown = 300
}

2.2 类型系统增强特性

• 支持通过x-enumNames保留原始枚举命名（兼容NSwag/NJsonSchema）
• 自动生成JSDoc注释（源自x-enum-descriptions）
• 严格模式下的运行时类型校验
• 完善的泛型支持与组合类型推导

3. 完整安装与配置指南

3.1 环境准备

bash复制# 确保Node.js版本≥16
node -v
# 推荐使用pnpm（npm/yarn同样支持）
pnpm