在 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'