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

我在 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 中表示这一点？

互斥参数是可能的（某种程度上）开放API 3.x:

• 将互斥参数定义为对象属性，并使用oneOf or maxProperties将对象限制为只有 1 个属性。
• Use the 参数序列化方法 style: form and explode: true，以便该对象被序列化为?propName=value.

使用的示例minProperties and 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

Using 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 Editor 尚不支持上述示例（截至 2018 年 3 月）。这个问题似乎涵盖了参数渲染部分。

OpenAPI 规范存储库中还有一个开放提案支持查询参数之间的相互依赖性因此，也许规范的未来版本将有更好的方法来定义此类场景。