如何在 OpenAPI 中定义枚举映射？

Question

我正在设计一个 API，我想定义一个枚举严重性，其值可以为低、中或高。在内部，严重性存储为整数，因此我想将它们分别映射到 2,1 和 0。有没有办法在 OpenAPI 定义中做到这一点？这就是我目前的严重性：

 severity:
   type: string
   enum:
   - HIGH
   - MEDIUM
   - LOW

Answer 1

开放API 3.1

OpenAPI 3.1 使用最新的 JSON Schema，在 JSON Schema 中注释各个枚举值的推荐方法是使用oneOf+const而不是enum。title通过这种方式，您可以指定枚举值的自定义名称 ( ) 和描述。

Severity:
  type: integer
  oneOf:
  - title: HIGH
    const: 2
    description: An urgent problem
  - title: MEDIUM
    const: 1
  - title: LOW
    const: 0
    description: Can wait forever

OpenAPI 3.0 和 2.0

这些版本无法为枚举值定义自定义名称，但某些工具x-为此目的提供了扩展。例如：

• 自动休息支持x-ms-enum。

• NSwag支持x-enumNames：

  Severity:
    type: integer
    enum: [2, 1, 0]
    x-enumNames: [HIGH, MEDIUM, LOW]
  

• openapi-typescript-codegen支持x-enum-varnames：

  Severity:
    type: integer
    enum: [2, 1, 0]
    x-enum-varnames: [HIGH, MEDIUM, LOW]
  

请咨询您的工具供应商，看看他们是否有类似的扩展。

Answer 2

开放API 3.0

您可以使用描述：

Severity:
  type: integer
  enum: [2, 1, 0]
  description: >
    dictionary:
      * 2 HIGH
      * 1 MEDIUM
      * 0 LOW

它不会影响自动代码生成，但会在生成的文档中可见。