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

Question

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

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

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

Answer 1

2.0 规范不支持，3.0 也不支持。

以下是 OpenAPI 规范存储库中的相应提案：
Accommodate legacy APIs by allowing query parameters in the path
Querystring in Path Specification

Answer 2

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

基本上，您可以通过在 URL.

中添加斜线 (/) 来对同一路径进行两个定义

这样，您可以使用 ?filter1= 参数为 <baseURL>/path 设置一个响应，并使用 ?filter2= 参数为 <baseURL>//path 设置另一个响应。为每个定义提供唯一的 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

在 swagger 定义位置中，显式类型是定义这些变量的内容。您拥有所有必需的字段以避免变量冲突，对于 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

Answer 4

在 Swagger 中，您可以添加 ? 以使端点不同。

即/文章和/文章?:

在 Swagger 编辑器中使用 ? 时，您将看到错误：

但是在您的最终 Swagger 页面上会有标记 VALID

附加信息：

记住重复条目的唯一性operationId

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

How to define different query parameters for same path in OpenAPI (Swagger)?

swagger

openapi