如何在AsyncAPI中定义带有指定固定值的枚举类型？

AsyncAPI 数据模型基于 JSON Schema 实现，原生enum关键字仅支持枚举可选值集合，不支持直接为每个枚举项绑定自定义关联数值，不存在遗漏配置的问题，这是原生语法的能力边界。

针对需要匹配C#显式赋值枚举的需求，有两种成熟可行的实现方案：

方案1：使用anyOf+const标准语法（优先推荐） #

这是JSON Schema规范支持的标准写法，目前绝大多数主流AsyncAPI生态工具、代码生成器都能正确识别，可直接生成和遗留代码结构完全一致的枚举类型，示例定义如下：

components:
  schemas:
    OrderStatus:
      type: integer
      anyOf:
        - const: 30
          title: Ordered
        - const: 40
          title: UnderDelivery
        - const: 50
          title: Deliveret
        - const: 99
          title: Cancelled

注意：你提供的C#代码中Deliveret存在拼写错误，如果是遗留代码的既定写法请保持一致，如果是笔误请同步修正两端定义，避免序列化/反序列化映射失败。

这种写法会严格约束字段的取值只能是指定的4个整数值，同时通过title字段绑定每个值对应的枚举项名称，代码生成阶段会自动映射为带显式数值赋值的C#枚举。

方案2：使用自定义扩展字段兜底 #

如果你当前使用的AsyncAPI工具链版本较旧，不支持识别上述anyOf写法，可以通过自定义扩展字段补充枚举名和值的映射关系，示例如下：

components:
  schemas:
    OrderStatus:
      type: integer
      enum: [30, 40, 50, 99]
      x-enum-names:
        - Ordered
        - UnderDelivery
        - Deliveret
        - Cancelled

不同工具使用的自定义扩展字段名可能存在差异，常见的还有x-enum-varnames，根据你使用的代码生成器文档配置即可。这种方案属于兼容旧工具的兜底选项，需要工具侧支持识别对应扩展字段才能正确生成匹配的枚举类型。

落地注意事项 #

• 如果消息序列化采用整数传输枚举值，只要约束字段取值范围和目标枚举值一致，即使代码生成阶段的名称映射有偏差，也可以通过自定义序列化转换器保证和遗留代码兼容
• 不建议用字符串类型枚举模拟数值枚举，会导致和遗留C#代码的序列化规则不匹配，增加联调成本

内容的提问来源于stack exchange，提问作者CruelIO