43

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

4

4 回答 4

33

在OpenAPI 3.x中可能（有点）互斥参数：

  • 将互斥参数定义为对象属性，并使用oneOf或maxProperties将对象限制为仅 1 个属性。
  • 使用参数序列化方法 style: formand explode: true，使对象序列化为?propName=value。

minProperties使用andmaxProperties约束的示例：

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


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

于 2018-03-09T17:38:37.343 回答
15

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

您能做的最好的事情是在参数描述中明确要求，并按照相同的行添加自定义的 400 Bad Request 描述。

在https://github.com/OAI/OpenAPI-Specification/issues/256有一些关于在 OpenAPI 规范的下一版本中实现这一点的可能方法的讨论。

于 2015-05-22T13:41:27.337 回答
6

改变你的 API 设计怎么样？目前你有一种方法，3个参数。如果我理解得很好，用户必须始终只提供一个参数，并且必须取消设置剩余的两个参数。

对我来说，API 将更适用于三个端点——比如

/user/byName?name=
/user/bySite?name=
/user/bySurvey?name=
于 2015-05-30T21:48:49.717 回答
2

另一种方法是传入一个带有枚举的过滤器类型参数，以及一个带有要使用的值的过滤器值。

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

您可以选择是否需要它。但是，如果需要一个，它们都应该是。

于 2016-11-23T23:13:54.937 回答