Question

我在下面定义了一个swagger 2.0资源。如何制作“param1或param2”？调用者必须传递param1或param2。

/some/res:
put:
  summary: some resource
  responses:
    200:
      description: Successful response
      schema:
        $ref: '#/definitions/SomeResponse'
  parameters:
    - name: param1
      type: string
      description: param1
      in: formData
      required: false
    - name: param2
      type: string
      description: param2
      in: formData
      required: false

Answer 1

OpenAPI（fka Swagger）规范不支持条件或互斥参数（任何类型）。

有一项开放式功能请求：
Support interdependencies between query parameters

Answer 2

在Describing Parameters Swagger文档的参数依赖关系部分：

Swagger不支持参数依赖项和互斥参数。 https://github.com/OAI/OpenAPI-Specification/issues/256有一项公开功能请求。

截至2017年6月，该问题有21个赞成票，成为该项目中第三个最受欢迎的问题。

Answer 3

Swagger规范不支持条件要求或包含/排除参数。

我建议在说明中清楚说明您的查询参数包含/排除规则。然后使用验证框架，该框架取决于您的语言（即Java的javax.validation，restify-validation for restify等），相应地验证参数。

Answer 4

此问题中的特定方案 - 包含param1或param2的表单数据正文的POST / PUT / PATCH请求 - 可以使用OpenAPI 3.0和oneOf来定义：

openapi: 3.0.0
...

paths:
  /some/res:
    put:
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - type: object
                  properties:
                    param1:
                      type: string
                  required:
                    - param1
                  additionalProperties: false
                - type: object
                  properties:
                    param2:
                      type: string
                  required:
                    - param2
                  additionalProperties: false

对于Swagger UI用户的注意事项：表单数据UI以及针对OpenAPI 3.0定义的oneOf模式are not available的示例呈现。

Swagger 2.0 - 如何制作＆＃34;一个或另一个＆＃34;需要参数？

4 个答案: