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

Question

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

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

类似于 REST 的可变参数。

Answer 1

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