Swagger参数多态性

Question

是否可以在Swagger中定义多种类型的输入参数?

的例子:我有API，地址资源使用URL http://localhost/tasks/{taskId}。但每个任务都包含整数id和字符串uuid。我想允许用户通过id或uuid来地址资源-因此http://localhost/tasks/123和http://localhost/tasks/51f12dbc-02e7-41a6-ab81-2381caea0176 url都是有效的。

但是，关于swagger文档(https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameter-object)参数对象只能有单一类型

类型:必需的。参数的类型。由于参数不在请求体中，因此它仅限于简单类型(即不是对象)。必须是"string"、"number"、"integer"、"boolean"、"array"或"file"中的一个。

那么我如何将输入路径参数描述为字符串/整数?

Answer 1

在Swagger规范中没有办法定义属于多个类型的参数。

在你的情况下，我认为你可以使用字符串来解决问题，它可以代表字符串(例如;"51f12dbc- 027e7 -41a6-ab81-2381caea0176")和整数(例如:

Answer 2

这可以在OpenAPI 3.0中使用oneOf:

openapi: 3.0.0
...
paths:
  /tasks/{taskId}:
    parameters:
      - in: path
        name: taskId
        required: true
        schema:
          oneOf:
            - type: integer
              example: 123
            - type: string
              format: uuid
              example: 51f12dbc-02e7-41a6-ab81-2381caea0176