如何在Swagger(OpenAPI)中定义互斥查询参数？

Question

我在Swagger中有一系列参数

                    "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中表现出来？

Answer 1

不幸的是,目前在Swagger中这是不可能的."required"只是一个布尔值,没有办法表示参数之间的相互依赖关系.

您可以做的最好是清除参数描述中的要求,并在同一行中输入自定义400错误请求描述.

(https://github.com/swagger-api/swagger-spec/issues/256上有关于在下一版Swagger中实现此功能的可能方法的讨论)

Answer 2

如何更改API设计？目前你有一个方法,3个参数.如果我理解得很好,用户必须始终提供一个参数,并且必须取消其余两个参数.

对我来说,API更适用于三个端点

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

Answer 3

在OpenAPI 3.0中，互斥参数是可能的（一种）：

• 将互斥参数定义为对象属性，然后使用oneOf或maxProperties将对象限制为1个属性。
• 使用参数序列化方法 style: 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：

      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

使用的另一个版本oneOf：

      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月）。这个问题似乎涵盖了参数呈现部分。

OpenAPI规范存储库中还存在一个开放的建议，以支持查询参数之间的相互依赖性，因此，规范的未来版本可能会有更好的方法来定义此类方案。