OpenAPI中的枚举映射详解

OpenAPI 本身并不直接支持将枚举键映射到对应的值。如果我们有如下所示的 C# 枚举：

    枚举方向 {  
      上 = 0;  
      下 = 1;  
      左 = 2;  
      右 = 3;  
    }

对应的OpenAPI json文件会缺少枚举常量。为了提供这些枚举常量的名称，我们可以使用x-enum-varnames扩展。这个扩展可以让我们为枚举提供额外的元数据，比如在代码中使用的变量名。

下面是我们在 OpenAPI JSON 文件中表示我们 C# 示例中的 Direction 枚举类型的方法：

{  
  "components": {  
    "模式": {  
      "方向": {  
        "type": "整数",  
        "enum": [0, 1, 2, 3],  
        "x-enum-varnames": ["上", "下", "左", "右"]  
      }  
    }  
  }  
}

解释。

• type: 类型设为整型，因为在 C# 中枚举的值是整数。
• enum: 此数组包含了枚举的所有可能整数值。
• x-enum-varnames: 这是一个自定义扩展，列出了每个枚举值对应的变量名。此扩展不是官方 OpenAPI 规范的一部分，但通常用来提供额外的上下文或元数据。

结论

尽管 OpenAPI 本身不直接支持枚举的键值映射，但可以通过使用类似 x-enum-varnames 的扩展来灵活地包含额外的元数据。

客户端生成器工具如 openapi-generator-cli 可以利用此扩展为生成的枚举提供键值对映射。

即使这些工具不直接支持枚举类型，我们也可以通过后续处理来生成这些枚举类型。

const extractEnums = (openApiDoc: OpenAPIObject) => {  
  const schemas = openApiDoc.components?.schemas;  
  if (!schemas) return {};  
  const enumConstants = {} as Record<string, string>;  
  for (const [key, schema] of Object.entries(schemas)) {  
    if ("enum" in schema && "x-enum-varnames" in schema) {  
      const enumValues = schema.enum as number[];  
      const enumNames = schema["x-enum-varnames"] as string[];  
      const enumMap = enumNames.reduce((acc, name, index) => {  
        acc[name] = enumValues[index];  
        return acc;  
      }, {} as Record<string, number>);  
      const enumKey = key.replaceAll(".", "_");  
      enumConstants[key] = `  
    export const ${enumKey} = {  
    ${enumNames.map((name) => `${name}: ${enumMap[name]}`).join(",\n")}  
    } as const;  
      `;  
    }  
  }  
  return `export namespace enums {  
    ${Object.values(enumConstants).join("\n")}  
  }`;  
}