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 does not support oneOf and anyOf。您可以做的最多就是使用typeless schema：

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来定义您的确切方案。

Answer 2

我不知道是否可以像使用Swagger一样注释您的API。但我的建议是简化/统一您的API。如果您考虑一下，如果您要支持批量（意味着一组对象），那么就没有理由对单个对象进行特殊处理。您应该只更改API以始终采用数组，如果有人想要执行单个对象，那么就是具有单个元素object :: Nil的列表的情况。

Answer 3

如果你想发送对象，只需删除@OA\Items()

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

告诉Swagger请求正文可以是单个对象还是对象列表

3 个答案: