Swagger：在同一 REST 操作中组合路径和查询参数答案

【问题标题】：Swagger: Combine Path and Query Parameters in Same REST OperationSwagger：在同一 REST 操作中组合路径和查询参数
【发布时间】：2019-11-13 21:38:25
【问题描述】：

你可以在 Swagger 2.0 或 3.0 中同时使用路径参数和查询参数吗？例如，给定以下基本 URL 和路径参数：

/api.example.com/{path}

是否可以添加查询参数，如：

/api.example.com/{path}?<query_param>=<query_value>

我的用例是 DELETE 操作：{path} 指的是要删除的对象 ID，我想添加一个标志，以便请求者可以指定是否尝试强制删除通常不会删除的对象可删除（想想在 Linux 中使用rm -f 删除一个非空目录）。然后 URL 将如下所示：

/api.example.com/{objectID123}                     (regular delete; will fail if object is non-empty)

/api.example.com/{objectID123}?forceDelete=True    (force delete)

我知道我可以将对象 ID 和 forceDelete 标志都指定为查询参数，但这意味着将 DELETE 操作重写为仅基于查询参数，而其他操作都基于路径参数；我希望保持一切一致。

我阅读了文档，但没有明确解决这个问题。请注意，如果有我不知道的最佳做法，我愿意接受另一种处理 DELETE 操作的方法。

【问题讨论】：

标签： swagger

【解决方案1】：

是的，你可以在同一个操作中有不同的参数类型。

openapi: 3.0.2
...
paths:
  /api.example.com/{objectID}:
    delete:
      parameters:
        - in: path
          name: objectID
          required: true
          schema:
            type: integer
        - in: query
          name: forceDelete
          schema:
            type: boolean
            default: false

【讨论】：

在这里操作：谢谢！一旦我确认它有效，我会试一试并将您的答案标记为已接受。