Swagger OpenApi3中多结构requestBody的正确定义方法

原写法的问题 #

你给出的全罗列字段的写法不正确，存在三个明显问题：

• 语法错误：type_id 字段后缺少冒号，会直接导致YAML解析失败
• 类型不匹配：第二种结构中user为布尔类型，原定义误写为integer，和实际业务场景不符
• 逻辑规则缺失：全罗列的方式仅能将所有字段标记为可选，无法体现「status+user_id 和 user+type_id 是两组互斥的字段组合，二选一使用」的业务规则，调用方极易出现多传、错传字段的问题。

该写法仅能临时凑合用做调试，完全不适合用于生产环境的接口定义。

正确的requestBody定义方式 #

使用OpenAPI原生提供的oneOf关键字即可实现两种结构的分别描述，同时可以把两种结构共有的form_id、submission_id抽出来复用，规范写法如下：

requestBody:
  description: Check integration status.
  content:
    application/json:
      schema:
        type: object
        # 两种结构都必须传的公共字段
        required:
          - form_id
          - submission_id
        properties:
          form_id:
            type: integer
            example: 55426
          submission_id:
            type: integer
            example: 28
        # 声明互斥的两种字段组合
        oneOf:
          # 第一种结构：带status和user_id
          - properties:
              status:
                type: integer
                example: 1
              user_id:
                type: string
                example: "74285"
            required:
              - status
              - user_id
          # 第二种结构：带user和type_id
          - properties:
              user:
                type: boolean
                example: true
              type_id:
                type: integer
                example: 1
            required:
              - user
              - type_id

如果需要更清晰的区分，还可以给oneOf下的每个schema加title字段标注对应场景，调试工具会直接展示标题做区分。

调试环节的使用说明 #

如果用上述oneOf的规范写法，现在主流的OpenAPI调试工具（包括Swagger UI自带的Try it out功能）都会自动提供两种结构的切换选项，选中对应场景就会自动生成对应字段的示例，不需要手动增减字段，出错概率更低。
如果坚持用全罗列的旧写法，调试时确实可以只传对应场景的字段，但因为没有规则约束，很容易漏传必传字段或者传错字段类型，非常不推荐。

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