在 openAPI 3.1 中定义精确的自定义属性答案

【问题标题】：Define exact custom Properties in openAPI 3.1在 openAPI 3.1 中定义精确的自定义属性
【发布时间】：2022-01-05 01:26:09
【问题描述】：

我有一个我想要描述的 JSON 模式，一个 JSON 对象，它有一个 additionalProperties 节点，其中包含一个键值对数组。

{
  "additionalProperties": [
    {
        "key": "optionA",
        "value": "1"
    },
    {
        "key": "optionB",
        "value": "0"
    },
    {
        "key": "optionC",
        "value": "1"
    }
  ],
}

虽然我可以像这样使用相当通用的架构

    additionalProperties:
      properties:
        key:
          type: string
        value:
          type: string
      required:
        - key
        - value
      type: object

理想情况下，我希望解释可能出现的各种键以及它们的含义。 IE。 optionA 表示这个，OptionB 表示那个。有没有办法可以描述将出现在数组中的确切选项？

【问题讨论】：

您可以使用“描述”。
你的意思是key 值是一个枚举吗？ key 值是否会影响其他任何内容，例如它们是否控制相应 value 键的可能值？

标签： json yaml swagger openapi

【解决方案1】：

description 字段用于向读者提供不必仅由架构解释的附加信息或上下文。

additionalProperties:
  description: Your explanation goes here. Note that you can use markdown formatting if desired.
  properties:
    key:
      type: string
    value:
      type: string
  required:
    - key
    - value
  type: object

如果它们都是使用oneOf、allOf 或anyOf 的已知值，您还可以更准确地描述架构中的选项。 (Documentation here)

additionalProperties:
  properties:
    anyOf:
      - $ref: '#/components/schemas/optionA'
      - $ref: '#/components/schemas/optionB'
      - $ref: '#/components/schemas/optionC'

【讨论】：