13

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

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

类似于 REST 的可变参数。

4

3 回答 3

16

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

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

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

OpenAPI 3.0支持oneOfand 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 来定义您的确切场景。

于 2015-08-03T06:12:38.693 回答
4

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

于 2015-07-31T21:15:32.820 回答
0

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

 *   @OA\RequestBody(
 *      required=true,
 *      @OA\JsonContent(
 *         ref="#/components/schemas/Brand"
 *      )
 *   ),
于 2021-05-18T07:35:42.510 回答