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

【问题标题】：How to define a nested array in OpenAPI?如何在 OpenAPI 中定义嵌套数组？
【发布时间】：2022-01-25 23:04:30
【问题描述】：

我想定义这个

     "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

但我收到“架构无效”错误。有没有其他方法来定义这个？

【问题讨论】：

标签： yaml openapi

【解决方案1】：

数组必须使用 items 关键字。

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

【讨论】：

根据@Helen 的想法，如果内部数组始终包含 2 个元素，您可以添加 minItems: 2 和 maxItems: 2 用于文档目的。尽管 IMO，如果您要开始定义这样的标准，最好明确定义可重用的对象模式。（无论哪种方式，这都是所问问题之外的优化。）

【解决方案2】：

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

# 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

【讨论】：