LeonardChallis LeonardChallis - 1 month ago 13
PHP Question

Can I make swagger-php use arrays on the query string?

I use Swagger-php. When I define a parameter that's on the query string it can be an array. But from what I can see, it doesn't support this kind of querystring:

https://api.domain.tld/v1/objects?q[]=1&q[]=5&q[]=12


I believe this would be set in the
collectionFormat
field
if possible. Currently I've just been using
pipes
, but I want to use the above format, and have Swagger-UI reflect this, too. However, I read this github issue which has left me wondering if this is actually possible and I've just missed it?

An example of my Swagger-PHP definition:

/**
* @SWG\Parameter(
* name="ids",
* in="query",
* description="A list of IDs (separated by pipes) to filter the Returns",
* required=false,
* type="array",
* @SWG\Items(
* type="integer",
* format="int32"
* ),
* collectionFormat="pipes"
* )
*/


Which results in the following JSON:

"parameters": {
"ids": {
"name": "ids",
"in": "query",
"description": "A list of IDs (separated by pipes) to filter the Returns",
"required": false,
"type": "array",
"items": {
"type": "integer",
"format": "int32"
},
"collectionFormat": "pipes"
}
}

Answer

Unfortunately, it is not possible to get exactly the URL you provide (https://api.domain.tld/v1/objects?q[]=1&q[]=5&q[]=12) for an array query parameter.

Assuming that you want to define a 1 dimension array query parameter (the github issue you're refering to concerns multi-dimensional arrays), here's what the current OpenAPI (fka. Swagger) Specification can propose:

  • If you use an array with a collection format like pipes (you can also use csv, ssv or tsv to get different separators) the URL will look like this:

    https://api.domain.tld/v1/objects?q=1|5|12
    

    But this is not the syntax you're looking for: all array items are defined in a single q query parameter.

  • Fortunately, there is another collection format multi allowing to define each array's item in its own q parameter, with this one you can almost get what you want minus the []:

    https://api.domain.tld/v1/objects?q=1&q=5&q=12
    

You can read more about this in this OpenAPI (fka. Swagger) tutorial (disclosure: I wrote it) and in the specification itself (ParameterObject description)