如何在 OpenAPI 中定义嵌套数组？

Question

我想定义这个

     "locationPoly": [
          [-87.63466, 24.50182],
          [-80.03074, 24.50182],
          [-80.03074, 31.00107],
          [-87.63466, 31.00107],
          [-87.63466, 24.50182]
        ],

在我的 OpenAPI YAML 模式中，我这样定义它：

                  locationPoly:
                    type: array
                    properties:
                      type: array
                      properties:
                        type: number

但我收到“架构无效”错误。 还有另一种定义方式吗？

Answer 1

Arrays 必须使用items关键字。

locationPoly:
  type: array
  items:
    type: array
    items:
      type: number

如果内部 arrays 始终包含 2 个元素，则可以添加minItems: 2和maxItems: 2用于文档目的：

locationPoly:
  type: array
  items:
    type: array
    items:
      type: number
    minItems: 2
    maxItems: 2

Answer 2

在您的示例中， locationPoly数组似乎包含坐标。 一对坐标可以被认为是一个元组（有序列表）。 如果您使用的是OpenAPI 3.1 （或将来会使用它），它具有用于定义元组的prefixItems关键字。 这样，您可以为元组的各个元素提供单独的描述（即，在您的示例中，对于内部 arrays 的第一项和第二项）。

# openapi: 3.1.0

  locationPoly:
    type: array
    items:
      $ref: '#/components/schemas/Coordinates'
...

Coordinates:
  type: array
  prefixItems:
    # The 1st item
    - type: number
      description: Latitude
      minimum: -90
      maximum: 90
    # The 2nd item
    - type: number
      description: Longitude
      minimum: -180
      maximum: 180
  minItems: 2
  maxItems: 2
  additionalItems: false # Can be omitted if maxItems is specified