Swagger参数多态性

Question

可以在Swagger中定义多种类型的输入参数吗？

示例：我有使用URL http://localhost/tasks/{taskId}资源的API。 但是每个任务都包含整数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 ）参数对象只能具有单个类型

类型：必填。 参数的类型。 由于参数不在请求正文中，因此它仅限于简单类型（即不是对象）。 该值必须是“字符串”，“数字”，“整数”，“布尔值”，“数组”或“文件”之一。

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

Answer 1

在Swagger规范中，无法定义属于多个类型的参数。

在您的情况下，我认为您可以使用字符串来解决，该字符串可以在path参数中表示字符串（例如“ 51f12dbc-02e7-41a6-ab81-2381caea0176”）和整数（例如“ 123”），并且服务器应接收数据正确。

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