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

Posted 2023-02-19

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

【英文标题】：How to define different query parameters for same path in OpenAPI (Swagger)?

【发布时间】：2017-03-22 14:36:36

【问题描述】：

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

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

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

【问题讨论】：

相关：Swagger 2.0 - how to make “one or the other” parameter required?

OpenAPI 似乎是不必要的限制。我建议考虑 RAML

【参考方案1】：

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

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

【讨论】：

谢谢你，那我只需要平静下来。只是跟进，有什么方法可以构造一个像<baseURL>/path?filter1=value&filter2=value.....&filterN=value 这样的url，以便过滤器发生'n'次。我可以在我的 yaml 上记录这个并在 swagger code-gen 中构建

【参考方案2】：

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

基本上，您可以通过在 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'

我用路径参数试过了，效果很好！

【讨论】：

还是同样的错误。 Query strings in paths are not allowed.更多的是与问号的存在有关，而不是尝试添加新路径。

但是你需要问号干什么？据我了解，您不能将参数声明为路径的一部分，因此确实不应该有任何问号***.com/a/30252104/11342147

在某些情况下，您必须使用更复杂的 API，与基本的“CRUD”方法相比，这些 API 执行更广泛的操作。按照这个想法，您必须根据查询参数提供各种有效负载/响应。有人可能会说 - 只是添加另一个端点？但是，如果它仍然是相同的资源，只是不同的味道呢？另一个很好的例子可能是以下 github 评论 - github.com/OAI/OpenAPI-Specification/issues/…。

【参考方案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