如何在OpenAPI 3.0中定义搜索API的属性交叉依赖规则

你报错的核心原因是不需要把anyOf/oneOf放到required段里，这类组合校验关键字要和type: object、全局required字段平级，放在Schema的根层级即可。

完整的示例如下：

type: object
# 全局必填参数：所有请求都必须传这两个字段
required:
  - distance
  - distanceUnits
# 三类地理位置参数二选一的规则，和你原JSON Schema逻辑完全一致
anyOf:
  - required: [longitude, latitude]
  - required: [postalCode, countryCode]
  - required: [city, state, countryCode]
# 所有字段的类型定义，按需补充即可
properties:
  distance:
    type: number
    minimum: 0
  distanceUnits:
    type: string
    enum: [km, mi]
  longitude:
    type: number
    minimum: -180
    maximum: 180
  latitude:
    type: number
    minimum: -90
    maximum: 90
  postalCode:
    type: string
  countryCode:
    type: string
    description: 两位ISO 3166-1国家代码
  city:
    type: string
  state:
    type: string

注意事项 #

• 你原来写的dependencies规则可以省略，上面的anyOf逻辑已经完全覆盖了依赖校验：比如只要选择邮政编码的分支就必须同时传入国家代码，选择城市分支就必须同时传入省份和国家代码，选择经纬度就必须同时传入两个坐标，不会出现只传单个经纬度、只传邮政编码不传国家代码的情况。如果需要更严格的校验也可以保留dependencies字段，OpenAPI 3.0原生支持该关键字。
• 如果你的参数是URL查询参数而非请求体参数，OpenAPI 3.0不支持直接在查询参数层面使用anyOf这类组合规则，建议改为POST请求将参数放在请求体中传入，或者在接口描述中手动注明参数规则，Swagger编辑器不会对查询参数的组合规则做校验。
• 如果你希望严格要求三类参数只能选一类不能同时传多类，可以把anyOf换成oneOf，校验逻辑会更严格。

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