OpenAPI 3.0 中属性的交叉依赖

Question

我需要定义 swagger/OpenAPI v 3.0 文件以进行搜索 API。我的请求可以指定地理空间坐标（经度和纬度）或（邮政编码和国家代码）或（城市和州和国家代码）。除了这些，我还有几个强制属性，比如 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 构造，但是如果我试图在 required 部分中使用它，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。

OpenAPI 3.0 中属性的交叉依赖

Cross-dependency of attributes in OpenAPI 3.0

json

openapi

anyof