Swagger参数多态性

Question

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

示例:我有一个使用URL < code > http://localhost/tasks/{ taskId } 处理资源的API。但是每个任务都包含整数id和字符串uuid。我希望允许用户通过id或uuid来寻址资源，这样< code > http://localhost/tasks/123 和< code > http://localhost/tasks/51 F12 DBC-02e 7-41 a6-ab81-2381 caea 0176 URL都是有效。

但是，关于招摇的文件(https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameter-object）参数对象只能有一种类型

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

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

Answer 1

这可以在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

Answer 2

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

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