您如何在 Swagger 规范中定义一组不同的示例？

Question

我正在尝试使用静态 swagger 文件记录一个 API，该文件可以 return 一些 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 类型定义一个示例：

{
  "description": "A response",
  "schema": {
    "type": "string"
    }
  },
  "examples": {
    "application/json": {
      "name": "Dog"
    },
    "application/xml": {
      "name": "Cat"
    }
  }
}

如果您想添加完整的场景，我建议您在 HTML 页面中编写（或生成）完整的场景示例，并 link 它带有 externalDocs。您可以在根、操作、标签和模式中定义 externalDocs。

Answer 2

事实上，你可以。在响应对象中，放置一个带有数组的示例对象作为 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'

您如何在 Swagger 规范中定义一组不同的示例？

How do you define an array of different examples in a Swagger spec?

swagger

swagger-ui

swagger-2.0

swagger-editor