如何在Swagger中不使用anyOf定义含必选对象的数组？

问题背景 #

API响应中javascript数组必须包含两个固定对象，现有定义用anyOf仅能允许数组元素为两种类型之一，但无法强制两个对象都存在：

API响应示例

"response": {
    "meta": [ 
        [
            {}
        ]
    ],
    "javascript": [
        {
            "attribute": "type",
            "value": "applicaion/ld+json"
        },
        {
            "@context": "http://schema.org",
            "@graph": {
                "organization": {
                    "@type": "Organization",
                    "additionalType": "Organization",
                    "@id": "https://www.example.com/home",
                    "name": " Example name",
                    "sameAs": [
                        "https://twitter.com",
                        "https://www.facebook.com/",
                        "https://www.instagram.com/",
                        "https://www.linkedin.com/company/company/",
                        "https://en.wikipedia.org/wiki/_Group"
                    ],
                    "telephone": "083135",
                    "contactPoint": {
                        "@type": "ContactPoint",
                        "telephone": "083135",
                        "areaServed": {
                            "@type": "Country",
                            "name": "Example name"
                        }
                    },
                    "logo": {
                        "@type": "ImageObject",
                        "representativeOfPage": "True",
                        "url": "https://example.com/sites/default/files/_logo_4.svg"
                    }
                }
            }
        }
    ]
}

现有OpenAPI定义片段

pageResponse:
  allOf:
    - required:
      - pageAlias
      properties:
        statusCode:
          type: string
          example: 200
        statusMessage:
          type: string
          example: OK
        supportMessage:
          type: string
          example: Content returned
        response:
          type: object
          properties:
            content:
              type: object
              allOf:
              - $ref: "#/components/schemas/mainContent"
            meta:
              type: array
              items: 
                allOf:
                - $ref: "#/components/schemas/metaAttribute"
            javascript:
              type: array
              items:
                anyOf:
                - $ref: "#/components/schemas/javaScriptAttribute"
                - $ref: "#/components/schemas/javaScriptSchema"

解决方案 #

可以根据数组元素的顺序要求，选择以下两种方式替代anyOf：

1. 元素顺序固定的情况

如果javascript数组的两个对象顺序固定（第一个是javaScriptAttribute，第二个是javaScriptSchema），使用prefixItems定义固定位置的元素类型，同时限制数组长度为2：

javascript:
  type: array
  minItems: 2
  maxItems: 2
  prefixItems:
    - $ref: "#/components/schemas/javaScriptAttribute"
    - $ref: "#/components/schemas/javaScriptSchema"

2. 元素顺序不固定的情况

如果两个对象可以任意顺序排列，使用contains分别指定两种类型必须各出现至少一次，同时限制数组最小长度为2：

javascript:
  type: array
  minItems: 2
  uniqueItems: true # 可选，防止重复添加同一类型的对象
  contains:
    $ref: "#/components/schemas/javaScriptAttribute"
  contains:
    $ref: "#/components/schemas/javaScriptSchema"

说明 #

• anyOf的局限性：仅定义数组单个元素的可选类型，无法强制数组必须包含所有类型的实例，可能出现数组仅包含其中一种对象的情况，不符合需求。
• prefixItems：OpenAPI 3.0+支持，用于定义数组前N个元素的固定类型，适合顺序固定的场景。
• contains：OpenAPI 3.0+支持，表示数组至少包含一个符合指定schema的元素，多个contains组合可确保多种类型都存在。

内容的提问来源于stack exchange，提问作者Sidney Sousa