Swagger 2.0同一端点支持两种请求体的方案咨询

Swagger 2.0 规定一个 POST 操作只能定义一个 in: body 参数，所以你直接添加两个 body 参数必然会触发校验失败。结合你的场景（两个请求体存在公共字段），以下是几个可行的解决方案：

Swagger 2.0 支持在 Schema 中通过 oneOf 指定多个可选结构，既能符合规范，又能表达“两种请求体二选一”的逻辑。配置示例如下：

paths:
  /v1/endpoint:
    post:
      operationId: api.handle_endpoint
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: 两种请求体二选一
          required: true
          schema:
            oneOf:
              - $ref: '#/definitions/a'
              - $ref: '#/definitions/b'
definitions:
  a:
    type: object
    properties:
      commonField:
        type: string
      fieldA:
        type: integer
    required: [commonField, fieldA]
  b:
    type: object
    properties:
      commonField:
        type: string
      fieldB:
        type: boolean
    required: [commonField, fieldB]

注意：Swagger UI 2.x 对 oneOf 的渲染可能不够直观（不会分开展示两种请求体），但校验可以通过，后端仍能根据实际请求体结构分支处理。

如果允许调整接口路径，最直接的方式是将两个分支逻辑拆分为两个独立的 POST 端点，每个端点对应一种请求体，完全符合 Swagger 2.0 规范，可读性和维护性也更强：

paths:
  /v1/endpoint/a:
    post:
      operationId: api.handle_endpoint_a
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: 请求体a
          required: true
          schema:
            $ref: '#/definitions/a'
  /v1/endpoint/b:
    post:
      operationId: api.handle_endpoint_b
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: 请求体b
          required: true
          schema:
            $ref: '#/definitions/b'
definitions:
  a:
    type: object
    properties:
      commonField:
        type: string
      fieldA:
        type: integer
    required: [commonField, fieldA]
  b:
    type: object
    properties:
      commonField:
        type: string
      fieldB:
        type: boolean
    required: [commonField, fieldB]

利用两个请求体的公共字段，通过 Swagger 2.0 的 discriminator 特性区分请求体类型，这种方式更规范，Swagger UI 也能更好地识别展示：

paths:
  /v1/endpoint:
    post:
      operationId: api.handle_endpoint
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: 根据type字段区分请求体类型
          required: true
          schema:
            $ref: '#/definitions/BaseRequest'
definitions:
  BaseRequest:
    type: object
    discriminator: type  # 指定用于区分类型的公共字段
    properties:
      commonField:
        type: string
      type:
        type: string
        enum: [a, b]  # 枚举可选的类型值
    required: [commonField, type]
  a:
    allOf:
      - $ref: '#/definitions/BaseRequest'
      - type: object
        properties:
          fieldA:
            type: integer
        required: [fieldA]
  b:
    allOf:
      - $ref: '#/definitions/BaseRequest'
      - type: object
        properties:
          fieldB:
            type: boolean
        required: [fieldB]

这种方式下，后端可以直接根据 type 字段的值进入对应分支逻辑，同时 Swagger 会清晰展示两种请求体的结构差异。

内容的提问来源于stack exchange，提问作者Vijay Anand