告诉Swagger请求主体可以是单个对象或对象列表

Question

我正在使用Swagger和Scala来记录我的REST API.我想为POST,PUT和DELETE启用批量操作,并希望相同的路由接受单个对象或对象集合作为正文内容.

有没有办法告诉Swagger param是A类型的值列表还是A类型的单个值？

像REST的varargs之类的东西.

Answer 1

有没有办法告诉Swagger param是A类型的值列表还是A类型的单个值？

这取决于您使用的是OpenAPI 3.0还是OpenAPI(Swagger)2.0.

OpenAPI使用JSON Schema的扩展子集来描述主体有效负载.JSON Schema提供了oneOf和anyOf关键字来定义实例的多个可能模式.但是,不同版本的OpenAPI支持不同的JSON Schema关键字集.

OpenAPI 3.0支持oneOf和anyOf,因此您可以按如下方式描述此类对象或对象数组:

openapi: 3.0.0
...

components:
  schemas:
    A:
      type: object
    Body:
      oneOf:
        - $ref: '#/components/schemas/A'
        - type: array
          items:
            $ref: '#/components/schemas/A'

在上面的示例中,Body可以是对象A或对象数组A.

OpenAPI(Swagger)2.0 不支持oneOf和anyOf.您可以做的最多是使用无类型架构:

swagger: '2.0'
...

definitions:
  A:
    type: object
  # Note that Body does not have a "type"
  Body:
    description: Can be object `A` or an array of `A`

这意味着Body可以是任何东西 - 一个对象(任何对象!),一个数组(包含任何项目!),也是一个原语(字符串,数字等).Body在这种情况下,无法定义确切的结构.你只能在口头描述这个description.

您需要使用OpenAPI 3.0来定义您的确切方案.