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个属性。
使用parameter serialization method 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 Editor不支持上述示例（截至2018年3月）。 This issue似乎涵盖了参数渲染部分。

在OpenAPI规范库中还有一个开放的提案support interdependencies between query parameters，因此未来版本的规范可能有更好的方法来定义这些场景。

Answer 4

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

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

可以选择是否需要。但是，如果需要，他们都应该是。

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

4 个答案: