openapi 3.0 specify complex filter in parameters

Question

I have an api to specify in openapi 3.0 (.yml)

I struggle with specifying an optional filter parameter. Especially with dynamic keys for featureId. I looked at: https://swagger.io/docs/specification/data-models/dictionaries/

featureId's look like this: dws33231j The amount of featureId objects can vary

My Data structure:

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

curl should look like this: https://path/articles&filter[featureId1]=selectedOption1,selectedOption2,selectedOption6&filter[featureId2]=selectedOption8'

So far i have this, that is far from right. How do I specify dynamic keys?

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]

Possibly related: [OpenAPI path/query parameters nested structure serialization](https://stackoverflow.com/q/67745944/113116) — Helen, Jun 15 '21 at 21:29

score 1 · Accepted Answer · answered Jun 15 '21 at 21:28

Small typo: It's deepObject not deepobject.

Your filter schema for a string-to-array dictionary is almost correct, you only need to replace properties+featureId1 with additionalProperties:

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

BUT

Unfortunately, OpenAPI 3.0/3.1 does not support serializing such complex objects in the query string. Currently, a query object can only have primitive properties but not array properties or nested objects.

As a workaround, you can define the comma-separated values selectedOption1,selectedOption2 as a single string value rather than an array. Your backend will need to convert "selectedOption1,selectedOption2" into ["selectedOption1", "selectedOption2"] when processing the request.

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

openapi 3.0 specify complex filter in parameters

1 Answers1