OpenAPI定义含必填字段与互斥可选字段的JSON Schema

要实现你需要的「两个可选字段互斥」的约束，可以利用OpenAPI 3.x的not关键字来禁止请求体同时包含这两个字段，结合已有的必填字段定义即可完成配置。

修改后的完整OpenAPI描述如下：

openapi: 3.0.4
info:
  title: My API
  version: 1.0.0
paths:
  /my-endpoint:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: 
                - mandatoryField
              properties:
                mandatoryField:
                  type: string
                optionalFieldOne:
                  type: string
                optionalFieldTwo:
                  type: string
              # 禁止同时存在两个可选字段，满足互斥要求
              not:
                required:
                  - optionalFieldOne
                  - optionalFieldTwo

配置说明 #

• required: [mandatoryField] 确保请求体必须包含这个必填字段，符合你的第一个要求
• not关键字的作用是排除「同时包含optionalFieldOne和optionalFieldTwo」的非法情况，这样请求体的合法场景包括：
  1. 仅包含mandatoryField
  2. 包含mandatoryField和optionalFieldOne
  3. 包含mandatoryField和optionalFieldTwo

如果需要限制请求体不能出现未定义的额外字段，可以在schema层级添加additionalProperties: false：

# 在schema中添加该配置
additionalProperties: false

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