如何在OpenAPI（Swagger）中为同一路径定义不同的查询参数？

Question

我正在使用Swagger Codegen启动REST服务。对于不同的参数，我需要有不同的响应。

示例：<baseURL>/path可以使用?filter1=或?filter2=，并且这些参数应产生不同的响应消息。

我希望我的OpenAPI YAML文件分别记录这两个查询参数。这可能吗？

Answer 1

它在 2.0 规范中不受支持，在 3.0 中也不支持。

以下是 OpenAPI 规范存储库中的相应提案：
通过允许路径规范中的查询字符串中的查询参数来容纳遗留 API

Answer 2

如果您仍在寻找，我找到了解决此问题的方法。这有点像黑客，但它确实有效。

基本上，您可以通过在 URL 中添加斜杠 (/) 对同一路径进行两个定义。

这样，您可以<baseURL>/path使用该参数设置一个响应，并使用该参数?filter1=设置另一个响应。为每个定义提供唯一的值也很重要。<baseURL>//path?filter2=operationId

paths:
   /path/you/want:
      get:
         summary: Test 
         operationId: get1
         parameters:
         - name: filter1
         type: string
         in: path
         required: true
      responses:
         200:
            description: Successful response
            schema:
              $ref: '#/definitions/SomeResponse'

   /path/you//want:
     get:
         summary: Another test
         operationId: get2
         parameters:
         - name: filter2
         type: string
         in: path
         required: true
     responses:
       200:
         description: Successful response
         schema:
           $ref: '#/definitions/SomeOtherResponse'

我用路径参数尝试了这个，效果很好！