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

Question

我有一个 JSON 架构，我试图描述一个 JSON object，它有一个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

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

Answer 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的已知值，您还可以更准确地描述架构中的选项。 （ 文档在这里）

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