如何在Swagger（OpenAPI）中定义互斥查询参数？

我有扬鞭一系列参数，这样必须填写如何在Swagger（OpenAPI）中定义互斥查询参数？

    "parameters": [ 
        { 
         "name": "username", 
         "description": "Fetch username by username/email", 
         "required": false, 
         "type": "string", 
         "paramType": "query" 
        }, 
        { 
         "name": "site", 
         "description": "Fetch username by site", 
         "required": false, 
         "type": "string", 
         "paramType": "query" 
        }, 
        { 
         "name": "survey", 
         "description": "Fetch username by survey", 
         "required": false, 
         "type": "string", 
         "paramType": "query" 
        } 
       ],

的一个参数，但它并不重要哪一个，其他人可以留空。有没有办法在Swagger中表示这个？

来源

2014-01-15 lorless

不错的问题我不认为这是，如果你找到出路请分享:) –

我面临同样的问题。你有解决它吗？ – eskalera

不幸的是，它看起来像这个功能不可用 – lorless

不幸的是，目前在Swagger中这是不可能的。 “required”只是一个布尔值，并且无法表示参数之间的相互依赖关系。

您可以做的最好的事情就是明确参数描述中的要求，并在同一行中放入自定义的400错误请求描述。

（有在https://github.com/swagger-api/swagger-spec/issues/256关于扬鞭的下一个版本实现这种可能的方式有点讨论）

来源

2015-05-22 13:41:27

有关更改API的设计是什么？目前你有一个方法，3个参数。如果我理解的很好，用户必须始终提供一个参数，剩下的两个必须未设置。

对我来说，API会更可用具有三个端点样

/user/byName?name= 
/user/bySite?name= 
/user/bySurvey?name=

来源

2015-05-30 21:48:49

解决技术问题，但不是很安静。 –

一个替代方案是在过滤器中类型的参数来传递与一个枚举，并且与值的滤波值来使用。

例在：https://app.swaggerhub.com/api/craig_bayley/PublicAPIDemo/v1

可以要求或不，任您选择。但是，如果需要，他们都应该。

来源

2016-11-23 23:13:54

我的理解是否正确，在这种情况下，您的提案将产生API /用户？name = name＆filterType = [name | site | survey]？我同意，因为这是更重要的，因为我们有单一资源，因为它应该是（仍然有干净和可用的API）。 –

互斥参数在OpenAPI 3.0是可能的（排序的）：

定义互斥参数为对象属性和使用oneOf或maxProperties到对象限制为只有1属性。
使用parameter serialization methodstyle: form和explode: true，以便将对象序列化为?propName=value。

使用minProperties和maxProperties约束的一个例子：

openapi: 3.0.0 
... 
paths: 
    /foo: 
    get: 
     parameters: 
     - in: query 
      name: filter 
      required: true 
      style: form 
      explode: true 
      schema: 
      type: object 
      properties: 
       username: 
       type: string 
       site: 
       type: string 
       survey: 
       type: string 
      minProperties: 1 
      maxProperties: 1 
      additionalProperties: false

使用oneOf：使用oneOf

 parameters: 
     - in: query 
      name: filter 
      required: true 
      style: form 
      explode: true 
      schema: 
      type: object 
      oneOf: 
       - properties: 
        username: 
        type: string 
       required: [username] 
       additionalProperties: false 
       - properties: 
        site: 
        type: string 
       required: [site] 
       additionalProperties: false 
       - properties: 
        survey: 
        type: string 
       required: [survey] 
       additionalProperties: false

另一个版本：

 parameters: 
     - in: query 
      name: filter 
      required: true 
      style: form 
      explode: true 
      schema: 
      type: object 
      properties: 
       username: 
       type: string 
       site: 
       type: string 
       survey: 
       type: string 
      additionalProperties: false 
      oneOf: 
       - required: [username] 
       - required: [site] 
       - required: [survey]

请注意，Swagger UI和Swagger编辑器不支持以上示例（截至2018年3月）。 This issue似乎覆盖了参数渲染部分。

在OpenAPI规范存储库中还有一个开放的提议，要求support interdependencies between query parameters，因此规范的未来版本可能会有更好的方式来定义这样的场景。

来源

2018-03-09 17:38:37 Helen

如何在Swagger（OpenAPI）中定义互斥查询参数？

回答

相关问题