在OpenAPI-TS中生成TypeScript枚举的最佳实践

在使用OpenAPI规范定义API时，我们经常需要处理枚举类型。本文将以OpenAPI-TS项目为例，详细介绍如何通过OpenAPI规范生成符合预期的TypeScript枚举类型。

枚举定义的基本方式

在OpenAPI规范中，定义枚举最基础的方式是使用enum字段：

{
  "type": "integer",
  "enum": [0, 1, 2, 3]
}

这种方式生成的TypeScript类型会是联合类型：

type MyEnum = 0 | 1 | 2 | 3;

为枚举值添加语义化名称

为了让生成的代码更具可读性，我们需要为枚举值添加语义化名称。OpenAPI规范支持通过扩展字段来实现这一点：

{
  "type": "integer",
  "enum": [0, 1, 2, 3],
  "x-enum-varnames": ["DoNothing", "Reboot", "Shutdown", "RebootAndBootUpgraded"]
}

OpenAPI-TS配置

在OpenAPI-TS项目中，要生成真正的TypeScript枚举而非联合类型，需要在配置文件中进行相应设置：

// openapi-ts.config.ts
export default {
  plugins: [
    {
      enums: 'typescript',
      name: '@hey-api/typescript',
      exportInlineEnums: true
    }
  ]
}

完整示例

结合上述所有要点，一个完整的枚举定义示例如下：

{
  "type": "object",
  "properties": {
    "autopilot": {
      "type": "integer",
      "enum": [0, 1, 2, 3],
      "x-enum-varnames": [
        "DoNothing",
        "Reboot",
        "Shutdown",
        "RebootAndBootUpgraded"
      ],
      "description": "操作类型枚举"
    }
  }
}

这将生成如下的TypeScript代码：

export enum Autopilot {
  DoNothing = 0,
  Reboot = 1,
  Shutdown = 2,
  RebootAndBootUpgraded = 3
}

注意事项

1. 确保使用正确的扩展字段名x-enum-varnames而非x-enum-names
2. x-enum-varnames数组长度必须与enum数组长度一致
3. 在OpenAPI-TS配置中启用exportInlineEnums选项
4. 枚举名称应当遵循TypeScript的命名规范（PascalCase）

通过以上方法，我们可以从OpenAPI规范生成语义清晰、易于维护的TypeScript枚举类型，提高代码的可读性和可维护性。