如何在 Swagger (OpenAPI 3.1) 中定义互斥的查询和路径参数？

Question

我有这个路径

GET /pricing/{product-line}/countries/{country-code}:

，其中

product-line

是一个枚举字符串路径参数，由2个值组成：

product-A

，

product-B

。

作为请求的一部分，我想添加一个名为

includes

的查询参数，它是数组类型，其元素是字符串类型的枚举。

product-A

和

product-B

都有自己的一组枚举，这些枚举对它们来说是有效且专有的，例如

includes=A,B,C,D

，对

product-A

有效的枚举集和对

includes=F,G,H,I,J

有效的

product-B

枚举集。

使用 OpenAPI 3.x 实现这一目标的好方法是什么？

我尝试过以下方法，

        - name: includes
          in: query
          description: List of pricing components that are included in the response.
          style: form
          explode: false
          schema:
            anyOf:
            - $ref: '#/components/schemas/ListOfVerificationIncludes'
            - $ref: '#/components/schemas/ListOfVoiceIncludes'

这两个对象的架构模式看起来非常相似：

    ListOfVoiceIncludes:
      description: List of voice pricing components which will be used to retrieve pricing information for.
      type: array
      uniqueItems: true
      minItems: 1
      items:
        $ref: "#/components/schemas/VoiceIncludes"

和

    VoiceIncludes:
      description: Pricing component which will be used to retrieve pricing information for.
      type: string
      enum:
        - pstn
        - did
        - inapp
        - sip
        - features

我正在考虑将包含分成2个不同的查询参数，

voice-includes

和

verification-includes

，但我不确定如何实现路径参数和查询参数之间的互斥性，

product-A

与

includes-A

配合使用并且

product-B

与

includes-B

一起使用。

Answer 1

OpenAPI 没有很好的方法来定义单个端点的互斥查询参数，也不允许重复路径以这种方式定义不同的行为。您绝对可以“使其工作”，但如果您将其用于文档或代码生成，某些工具可能无法正确处理它。请参阅此答案以获得一些灵感https://stackoverflow.com/a/49199240/8564731

我自己没有尝试过，但我想知道是否可以使用 OpenAPI 3.1.x 或更高版本中完全支持的

if, then

语法。早期版本的 OpenAPI 3.0.x 不支持此关键字。当我有时间的时候我会尝试把一些东西放在一起