在 Swagger 响应中在数组中包含数组

Question

我正在尝试在 Swagger 中定义一个 API，其中 GET 的结果是模型 MainModel 的项目数组，每个项目都与另一个名为 AnotherModel 的模型的项目关联。像这样（这似乎是不允许的）：

responses:
    200:
      description: search results matching criteria
      schema:
        type: array
        items:
          $ref: '#/definitions/MainModel'
          type: array
          items: $ref: '#/definitions/AnotherModel'

Answer 1

首先，OpenAPI规范只支持字符串键的关联数组/字典，例如：

{
  "foo": 5,
  "bar": 2
}

但不是 C# 的 Dictionary<int, string>，其中键是 int。

关联数组是通过使用 object 模式和 additionalProperties 关键字指定数组值的类型来定义的。没有提到密钥类型，因为密钥总是字符串。

type: object
additionalProperties:
  type: <type of array values>
  # OR
  # $ref: '#/definitions/ValueModel'

同理，关联数组的数组可以定义如下：

type: array
items:
  type: object
  additionalProperties:
    type: <type of values in associative array>
    # OR
    # $ref: '#/definitions/ValueModel'

在你的例子中，关联数组的值是AnotherModel类型。所以内联定义看起来像：

      responses:
        200:
          description: search results matching criteria
          schema:
            type: array
            items:
              type: object
              additionalProperties:
                $ref: '#/definitions/AnotherModel'

definitions:
  AnotherModel:
    type: <whatever> # TODO

或者如果我们引入一个表示关联数组的中间体 MainModel（如您的原始示例）：

      responses:
        200:
          description: search results matching criteria
          schema:
            type: array
            items:
              $ref: '#/definitions/MainModel'

definitions:
  MainModel:  # Associative array of AnotherModel
    type: object
    additionalProperties:
      $ref: '#/definitions/AnotherModel'
  AnotherModel:
    type: <whatever> # TODO

一些注意事项：

通过 $ref 引用的每个模型都必须在 definitions 部分中定义。因此，如果您使用 $ref: '#/definitions/MainModel'，您的规范必须包括
```
  definitions:
    MainModel:
```
$ref 通过用它指向的定义替换自身及其所有兄弟元素来工作。这就是为什么您的原始示例无效：
```
  items:
    $ref: '#/definitions/MainModel'
    type: array
    items: $ref: '#/definitions/AnotherModel'
```
嵌套模型可以完全内联定义，也可以通过 $ref 引用，但不能两者兼而有之。

在 Swagger 响应中在数组中包含数组

Have arrays within arrays in a Swagger responses

api-design

swagger-2.0