openapi 3.0 在参数中指定复杂的过滤器

Question

我有一个要在 openapi 3.0 (.yml) 中指定的 api

我很难指定一个可选的过滤器参数。特别是对于 featureId 的动态键。我看了看：https://swagger.io/docs/specification/data-models/dictionaries/

featureId 如下所示：dws33231j featureId 对象的数量可能会有所不同

我的数据结构：

    [
        "featureId1" => [
            "selectedOption1",
            "selectedOption2"
        ],
        "featureId2" => [
            "selectedOption8"
        ],
        ...
    ]

curl 应如下所示：https://path/articles&filter[featureId1]=selectedOption1,selectedOption2,selectedOption6&filter[featureId2]=selectedOption8'

到目前为止，我有这个，这离正确的很远。如何指定动态键？

components:
  parameters:
    filter:
      name: filter
      in: query
      style: deepObject
      allowReserved: true
      description: 
      schema:
        $ref: "#/components/schemas/filter"

  schemas:
    filter:
      type: object
      properties:
        featureId1:
          description: id of the feature
          type: array
          items: 
            type: string
            example: [selectedOption1, selectedOption2, selectedOption6]

Answer 1

小错字：是deepObject 而不是deepobject。

您的字符串到数组字典的filter 架构几乎是正确的，您只需将properties+featureId1 替换为additionalProperties：

    filter:
      type: object
      additionalProperties:  # <-------
        description: id of the feature
        type: array
        items: 
          type: string
          example: [selectedOption1, selectedOption2, selectedOption6]

但是

不幸的是，OpenAPI 3.0/3.1 does not support 在查询字符串中序列化了如此复杂的对象。目前，查询对象只能有原始属性，不能有数组属性或嵌套对象。

作为一种解决方法，您可以将逗号分隔值selectedOption1,selectedOption2 定义为单个字符串值而不是数组。您的后端在处理请求时需要将"selectedOption1,selectedOption2" 转换为["selectedOption1", "selectedOption2"]。

    filter:
      type: object
      additionalProperties:
        type: string
        description: A comma-separated list of selected options
        example: selectedOption1,selectedOption2,selectedOption6