Are indexes in the query parameter array representable?

[jcarres-mdsol]

I understand how to represent in 2.0 and 3.0 these query parameters with OpenAPI:

?list=x&list=y

But I can't understand if it is possible or not (so I imagine, not?) to represent this:

?list[0]=x&list[1]=y

or this:

?obj[x][0]=a&obj[x][1]=b

We use indexes so we can mix arrays and maps with the same notation, i.e. we would also have:

?map[x]=1&map[y]=2

Is this even representable today? Any hack around it if not?

[jcarres-mdsol]

@webron, I think you originally added collectionFormat and style so probably you have given this some thought

[hkosova]

Your last example ?map[x]=1&map[y]=2 can be defined an an object parameter with style: deepObject:

      parameters:
        - in: query
          name: map
          schema:
            type: object
            properties:
              x:
                type: integer
              y:
                type: integer
          style: deepObject
          explode: true

or

      parameters:
        - in: query
          name: map
          schema:
            type: object
            additionalProperties:
              type: integer
          style: deepObject
          explode: true

Not sure about other examples though.

[harvzor]

.NET uses the ?list=x&list=y format for simple nested objects which currently works fine with Swagger/OpenAPI.

However, when .NET has to pass an array of objects, it switches to the ?list[0]=x&list[1]=y format, which is incorrectly parsed by Swagger because OpenAPI has no way of describing how it should be serialized.

This issue is better documented here: domaindrivendev/Swashbuckle.AspNetCore#1832

[DSchougaard]

I've just recently encountered this issue myself. Has anything new happened?

[septatrix]

This notation is also commonly used in PHP

[OleksiiBulba]

I have a question about the workaround: is it legit to name the parameter with brackets. E.g. for the author example it would be list[]. At least it solves the issue for just indexed query but not for maps.

[handrews]

@OleksiiBulba the OpenAPI parameter name syntax allows it. Although the question of whether non-percent-encoded [] is valid in a URL query string is complex (see Appendix E in the work-in-progress 3.0.4 and 3.1.1 specs, which are on their own branches). But if it's working for you in practice, then you're probably fine (I can't tell whether that PHP framework is encoding/decoding behind the scenes or if it's just relying on the interoperability problems of [ and ] in URLs being very rare).

[OleksiiBulba]

@handrews thanks for your prompt response!

Actually, I've already tried it with nelmio/api-doc-bundle (for Symfony) and it works absolutely ok.

P.S. For anyone who would find this comment: if your property is required, don't forget to add [] to the property name in required list, it will save you ~20 mins of life :D