如何在OpenAPI中定义查询参数的互斥可选规则？

对于你需要的id OR (firstName OR lastName)逻辑（即要么提供id，要么提供firstName/lastName中的至少一个，且两类参数不能同时存在），可以通过OpenAPI 3.x的oneOf关键字在查询参数的schema中实现，具体方案如下：

核心思路 #

查询参数本质是扁平的键值对集合，但OpenAPI 3.x允许为查询参数定义object类型的schema，并通过组合关键字（oneOf/anyOf）约束参数组合规则。我们可以把需求拆分为两个互斥场景，用oneOf限定请求必须匹配其中一个场景。

完整YAML示例 #

openapi: 3.0.3
info:
  title: 用户查询API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 根据条件查询用户
      parameters:
        - name: queryParams
          in: query
          required: true
          schema:
            oneOf:
              # 场景1：仅提供id，禁止出现firstName/lastName
              - type: object
                required: [id]
                properties:
                  id:
                    type: string
                    description: 用户唯一ID
                additionalProperties: false
              # 场景2：不提供id，但必须提供firstName或lastName至少一个
              - type: object
                properties:
                  firstName:
                    type: string
                    description: 用户名
                  lastName:
                    type: string
                    description: 用户姓氏
                # 确保至少有一个非空参数
                not:
                  required: []
                additionalProperties: false
          style: form
          explode: true
      responses:
        '200':
          description: 查询成功

关键细节说明 #

• oneOf的作用：确保请求查询参数只匹配其中一个场景，既避免同时传入id和姓名参数，也避免所有参数都不提供。
• additionalProperties: false：禁止传入schema未定义的其他查询参数，严格限定参数范围。
• not: { required: [] }：在第二个场景中，确保firstName和lastName至少有一个被提供，避免空请求。
• style: form和explode: true：保证查询参数以标准的key=value格式（如?id=123或?firstName=John）传递，符合HTTP查询参数的常规格式。

注意事项 #

• 该方案仅支持OpenAPI 3.0及以上版本，OpenAPI 2.0不允许为查询参数定义复杂的组合schema。
• 部分API文档生成工具或验证工具对查询参数的复杂schema支持度有限，建议在接口描述中补充文字说明规则，确保使用者清晰理解参数要求。

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