OpenAPI 3.0 中属性的交叉依赖

Question

我需要为搜索 API 定义 swagger/OpenAPI v 3.0 文件。 我的请求可以指定地理空间坐标（经度和纬度）或（邮政编码和国家/地区代码）或（城市和州以及国家/地区代码）。 除了这些之外，我还有一些强制性属性，例如 distance 和 distanceUnits。

我知道如何在 JSON 架构中做到这一点

            "dependencies": {
                "postalCode": ["countryCode"],
                "city": ["state", "countryCode"],
                "longitude": ["latitude"],
                "latitude": ["longitude"]
            },
            "anyOf": [
                {
                    "required": ["longitude", "latitude"]
                },
                {
                    "required": ["postalCode", "countryCode"]
                },
                {
                    "required": ["city", "state", "countryCode"]
                }
            ]
        }

但我在大摇大摆地定义它时遇到了麻烦。 OpenAPI 3.0 允许 oneOf 和 anyOf 构造，但如果我尝试在 必需部分，swagger编辑器给我一个错误。

任何帮助将不胜感激。

Answer 1

要为请求参数定义oneOf/anyOf 逻辑，您必须将所有参数定义为单个对象类型参数as explained here。

parameters:
  - in: query
    name: params  # This name will NOT appear in the request URL
                  # but will be used in generated client SDKs / server stubs
    required: true

    # serialize this object as ?key1=value1&key2=value2
    style: form
    explode: true

    schema:
      type: object
      properties:
        longitude: { ... }
        latitude:  { ... }
        postalCode:  { ... }
        countryCode: { ... }
        city:  { ... }
        state: { ... }
      anyOf:
        - required: [longitude, latitude]
        - required: [postalCode, countryCode]
        - required: [city, state, countryCode]

请注意，OpenAPI 3.0 不支持 JSON Schema 的 dependencies 关键字，但 OpenAPI 3.1（最新版本）支持。

OpenAPI 规范存储库中还有一个向support dependencies between individual parameter definitions 提出的现有功能请求。