1

我需要为搜索 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 编辑器会给我一个错误。

任何帮助将不胜感激。

4

1 回答 1

0

要为请求参数定义oneOf/anyOf逻辑，您必须将所有参数定义为单个对象类型参数，如此处所述。

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 不支持dependenciesJSON Schema 的关键字，但 OpenAPI 3.1（最新版本）支持。


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

于 2021-09-13T18:24:31.843 回答