OpenAPI3.0中属性的交叉依赖

Question

我需要为搜索API定义Swagger/OpenAPI V3.0文件。我的请求可以指定地理空间坐标（经度和纬度）或（邮政编码和国家代码）或（城市和州和国家代码）。除了这些，我还有几个更强制的属性，比如距离和距离单位。

我知道如何在JSON模式中做到这一点

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

但我很难用大摇大摆的方式来定义它。OpenAPI3.0允许One of和anyOf构造，但如果我试图在required部分使用它，swagger editor会给我一个错误。

任何帮助都将不胜感激。

Answer 1

要为请求参数定义之一/任意逻辑，必须将所有参数定义为单个对象类型参数，如本文所述。

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]

请注意，OpenAPI3.0不支持JSON模式的dependencies关键字，但OpenAPI3.1（最新版本）支持该关键字。

OpenAPI规范存储库中还有一个现有的特性请求，以支持各个参数定义之间的依赖关系。