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

Question

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

有没有办法告诉斯瓦格一个参数要么是A类型的值列表，要么是A类型的单个值？

类似于Rest的varargs。

Answer 1

如果要发送对象，只需删除@OA\Items（）

 *   @OA\RequestBody(
 *      required=true,
 *      @OA\JsonContent(
 *         ref="#/components/schemas/Brand"
 *      )
 *   ),

Answer 2

我不知道是否有可能像那样大摇大摆地为你的API添加注释。但我的建议是简化/统一API。如果你想一想，如果你打算支持批量（意思是一个对象数组），那么就没有理由对单个对象进行特殊处理。您只需将API更改为始终使用数组，如果有人想要使用单个对象，那么这就是带有单个元素的列表的情况object:：Nil。

Answer 3

有没有办法告诉斯瓦格一个参数要么是A类型的值列表，要么是A类型的单个值？

这取决于您使用的是OpenAPI 3.0还是OpenAPI（Swagger）2.0。

OpenAPI使用JSON模式的扩展子集来描述身体有效载荷。JSON模式提供了oneOf和anyOf关键字来为一个实例定义多个可能的模式。然而，不同版本的OpenAPI支持不同的JSON模式关键字集。

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可以是objectA，也可以是objectA数组。

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可以是任何对象（任何对象！），数组（包含任何项！），也是原语（字符串、数字等）。在这种情况下，无法定义确切的正文结构。您只能在说明中口头描述这一点。

您需要使用OpenAPI 3.0来定义您的确切场景。