在 OpenAPI 3.1.0 中枚舉恰好 2 個（略有不同）對象的數組？

Question

我需要記錄一個 REST 端點，它采用以下請求正文：

{
  "variables": [
    {
      "name": "groupGuid",
      "value": "...",
      "typeConstraint": "string",
    },
    {
      "name": "addMembership",
      "value": "...",
      "typeConstraint": "boolean",
    }
  ]
}

variables數組必須恰好包含 2 個對象：

• 一個具有所需name groupGuid和typeConstraint string ，
• 另一個具有所需的name addMembership和typeConstraint boolean 。

它們各自value的類型由typeConstraint指定，但value屬性的實際值在其他方面不受約束。

目前，我得到了這個，它非常不明確（並且可能是錯誤的）並且依賴於我手動包含的注釋：

  '/test':
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                variables:
                  type: array
                  uniqueItems: true
                  description: 'Must contain exactly 2 objects, with the following `name`s: (1) `groupGuid`: GUID of the group, (2) `addMembership`: Whether the task will add (true) or remove (false) members from the group.'
                  items:
                    type: object
                    additionalProperties: false
                    properties:
                      name:
                        enum:
                          - groupGuid
                          - addMembership
                        type: string
                      value:
                        type:
                          - string
                          - boolean
                      typeConstraint:
                        type: string
                        enum:
                          - string
                          - boolean
                        description: The type of `value`.

是否可以在 YAML / OpenAPI 3.1.0 中正確規范這些要求，如果可以，怎么做？ 謝謝。

Answer 1

如果您想要在示例正文中顯示兩個對象並接受其中一個或兩個，也許您可以使用anyOf 。

下面是一個例子

paths:
  /test:
    post:
      tags:
        - Test
      description: "Must contain exactly 2 objects, with the following `name`s: (1) `groupGuid`: GUID of the group, (2) `addMembership`: Whether the task will add (true) or remove (false) members from the group."
      requestBody:
          required: true
          content:
            application/json:
              schema:
                properties:
                  variables:                    
                    type: array
                    uniqueItems: true
                    items:
                      anyOf:
                        - $ref: '#/components/schemas/Object1'
                        - $ref: '#/components/schemas/Object2'
      responses:
        '200':
          description: Sucess

components:     
  schemas: 
    Object1:
      type: object
      description: "The value here is string"
      properties:
        name:
          type: string
        value:
          type: string
        typeConstraint:
          type: string
    Object2:
      type: object
      description: "The value here is boolean"
      properties:
        name:
          type: string          
        value:
          type: string
        typeConstraint:
          type: boolean