swagger - 如何在 Swagger 规范中定义不同示例的数组？

Question

我正在尝试使用静态 swagger 文件来记录 API，该文件可以返回一些包含如下所示数组的 JSON:

[
  {
    "type": "type A",
    "field A": "this field is specific to type A"
  },
  {
    "type": "type B",
    "field B": "this field is specific to type B"
  }
]

我尝试了几种不同的方法来使用多态或显式定义多个示例来定义我的规范。这些示例总是最终看起来像:

[
  {
    "type": "type A",
    "field A": "this field is specific to type A",
    "field B": "this field is specific to type B"
  }
]

要不就:

[
  {
    "type": "type A",
    "field A": "this field is specific to type A"
  }
]

有没有办法在我的 swagger 规范中定义一个示例，以便 swagger-ui 显示的示例有效负载将包含一个包含类型 A 示例和类型 B 示例的数组，就像我写的第一个 JSON？

Answer 1

事实上，你可以。在响应对象中，放置一个带有数组的示例对象作为 mime 类型的值。像这样:

    400:
      description: Bad Request
      examples:
        application/json:
          [
            {
              code:10000,
              message:"Missing Input Parameters",
              fieldA: "AAAAA"
            },{
              code:42,
              message:"Ask the question",
              fieldB: "BBBBBB"
            }
          ]
    default:
      description: Unexpected error
      schema:
        $ref: '#/definitions/Error'