如何在 swagger 中不使用 anyOf 来定义对象数组？

Question

我已经完成了编码，API 响应如下所示：

"response": {
    "meta": [ .. this is an array that contains arrays of objects
        [
            {}
        ]
    ]
    "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"
                    }
                }
            }
        }
    ]
}

但是，我需要为此端点编写 YML，并且我已经使用 swagger openapi: 3.0.0 完成了此操作。

注意 javascript 键，响应看起来像这样：

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 的情况下定义 javascript 键中的两个对象？ 这样做的原因是因为两个对象必须始终存在。它不是可选的。

我希望这个问题措辞得当。

Answer 1

对于大多数模式来说，不需要使用

allOf

。

allOf

主要用于将多个模式组合成一个更大的模式，或者解决 OpenAPI 3.x.x 的限制，允许兄弟姐妹使用

$ref

，您可能需要一个唯一的

description

或

title

作为属性。

例如

type: object
properties:
  some-prop:
    allOf:
      - title: this is a title
      - $ref: #/components/schemas/myschema

关于你的

javascript

数组。如果将引用放入

items

数组中，它将像一个元组一样运行，并验证数组实例以将这两个模式作为

javascript

数组的每个实例的索引 0 和 1。

关于您对

meta

.. 对象数组数组的评论，我更新了您的架构来处理该问题。

仅供参考，此模式总是会失败，因为您有一个

required: pageAlias

但它不属于此模式。

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