openapi, list of strings as query parameter - swagger

Question

I'm defining a query parameter, with openapi 3.0.1, as follows
{
"name" : "sort",
"in" : "query",
"description" : "Sorting criteria. Example: productCode,desc",
"required" : false,
"explode" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string"
}
}
}
On swagger-ui 3.51.1 if I add two strings
"parameter1,asc"
"parameter2,desc"
they are serialized correctly (as a list of strings with 2 elements), but if I add only one string
"parameter1,asc"
it will get serialized incorrectly as a list of strings with 2 elements (parameter1 and asc).
I do not understand why the string is exploded! Any help is greatly appreciated.

Answer 1

In your example, the query parameter has no style defined, so it defaults to style: form. Non-exploded form style treats the comma , as a separator of array items. This results in ambiguity because the values of your array items also use commas as an inner separator.
Possible solutions involve changing your backend code and/or the OpenAPI parameter definition.
Adjust the backend code so that it splits the received sort string on every second comma rather than every comma.
Or, use another serialization method for the sort array, for example:
explode: true to send the exploded array:
?sort=parameter1,asc&sort=parameter2,desc
style: pipeDelimited + explode: false to separate array items using | instead of commas:
?sort=parameter1,asc|parameter2,desc
Or, change sort to be an object/map instead of an array:
{
"name": "sort",
"in": "query",
"description": "Sorting criteria. Example: productCode,desc",
"required": false,
"explode": false,
"schema": {
"type": "object",
"additionalProperties": {
"type": "string",
"enum": ["asc", "desc"]
}
}
}
In this case, your current query string format
?sort=parameter1,asc,parameter2,desc
unambiguously corresponds to:
{
"parameter1": "asc",
"parameter2": "desc"
}