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

Question

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

有没有办法告诉 Swagger 参数是 A 类型的值列表或 A 类型的单个值？

类似于 REST 的可变参数。

Answer 1

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

Answer 2

Is there a way to tell Swagger that a param is either a list of values of type A or a single value of type A?

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

OpenAPI 使用 JSON 架构的扩展子集来描述正文有效负载。 JSON Schema 提供了 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 可以是对象 A 或对象数组 A。

OpenAPI (Swagger) 2.0 does not support oneOf and anyOf. The most you can do is use a :

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 3

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

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

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

Tell Swagger that the request body can be a single object or a list of objects

rest

scala

swagger

openapi