swagger - 如何在 OpenAPI (Swagger) 中为同一路径定义不同的查询参数？

Question

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

示例：<baseURL>/path可以使用?filter1=or ?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'

我用路径参数尝试了这个，它工作得很好！

Answer 3

在大摇大摆地定义位置时，类型明确地定义了这些变量。您拥有所有必需的字段以避免变量冲突，对于json正文，您必须引用声明或使用示例模式，如下所示。就我而言，我使用了模式示例而不是声明参考

/auth/account/password/reset/{userId}/{resetToken}:
post:
  consumes:
    - application/json
  parameters:
    - in: path
      name: userId
      type: string
      required: true
    - in: path
      type: string
      name: resetToken
      required: true
    - in: header
      name: authorization
      required: true
      type: string
    - in: body
      name: body
      required: true
      schema:
        type: object
        example:
          password: password
          confirmPassword: password
  responses:
    "200":
      description: OK