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

Question

我有一个api要在openapi 3.0 (.yml)

中指定

我很难指定一个可选的过滤器参数。特别是对于 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

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

openapi 3.0 specify complex filter in parameters

filter

openapi

query-parameters