如何在 OpenAPI 中的另一个表单参数的值上要求表单参数？

Question

我对带有表单数据的 POST 请求有以下 OpenAPI (Swagger) 定义。如何根据 type 参数的值改变所需的表单参数？

如果 type="email" 只需要 email 如果 type="phone" 只需要 country 和 phone 需要参数。

  /login:
    post:
      required:
      - type
      - password
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/SomeResponse'
      parameters:
        - name: type
          type: string
          in: formData
          enum: [email, phone]
        - name: email
          type: string
          in: formData
        - name: country
          type: string
          in: formData
        - name: phone
          type: string
          in: formData
        - name: password
          type: string

Answer 1

表单数据中的条件依赖可以在 OpenAPI 3 中表达，但不能在 OpenAPI 2.0 中表达 (swagger: 2.0)。

OpenAPI 3.1

此示例使用 OAS 3.1 中的新结构 if..then。

openapi: 3.1.0
...

paths:
  /login:
    post:
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Successful response

components:
  schemas:
    LoginRequest:
      type: object
      required:
        - type
        - password
      properties:
        type:
          type: string
          enum: [email, phone]
        email:
          type: string
        country:
          type: string
        phone:
          type: string
        password:
          type: string

      # Conditional dependencies
      allOf:
        # If type="email", then the `email` field is required
        - if:
            properties:
              type:
                const: email
          then:
            required: [email]

        # If type="phone", then the `country` and `phone` fields are required
        - if:
            properties:
              type:
                const: phone
          then:
            required: [country, phone]

OpenAPI 3.0.x

在 OAS 3.0 中，您可以使用以下 oneOf 构造来表达这些条件。

openapi: 3.0.3
...

paths:
  /login: ... # The path definition is the same as in the previous example


components:
  schemas:
    LoginRequest:
      type: object
      required:
        - type
        - password
      properties:
        type:
          type: string
          enum: [email, phone]
        email:
          type: string
        country:
          type: string
        phone:
          type: string
        password:
          type: string

      # Conditional dependencies
      oneOf:
        # If type="email" ...
        - properties:
            type:
              enum: [email]
          # ... then the `email` field is required
          required: [email]

        # If type="phone" ...
        - properties:
            type:
              enum: [phone]
          # ...then the `country` and `phone` fields are required
          required: [country, phone]

OpenAPI 2.0

在 OpenAPI 2.0 中，您最多可以将有条件的必需参数（示例中的 email、country 和 phone 定义为可选参数，并在操作说明and/or参数说明。

swagger: '2.0'
...

paths:
  /login:
    post:
      ...
      parameters:
        - name: type
          type: string
          in: formData
          enum: [email, phone]
          required: true
        - name: email
          type: string
          in: formData
          description: Required if type=email
        - name: country
          type: string
          in: formData
          description:  Required if type=phone
        - name: phone
          type: string
          in: formData
          description:  Required if type=phone
        - name: password
          type: string
          in: formData
          required: true

如何在 OpenAPI 中的另一个表单参数的值上要求表单参数？

How to require form parameters on the value of another form parameter in OpenAPI?

swagger

swagger-2.0

openapi

OpenAPI 3.1

OpenAPI 3.0.x

OpenAPI 2.0