Description
collectionFormat: multi sends an array by repeating the same parameter name. OpenAPI 2.0 permits it only for query and formData parameters.
Potential impact
Clients may serialize arrays differently from the server’s expectations, causing requests to fail.
Remediation
Choose serialization that matches the parameter location and actual request format. Use a supported format such as csv for path or header arrays; moving a parameter also requires matching the server’s request contract.
Examples
These examples move limit2 to query to use multi. The separate reusable path definition, limitParam, uses csv.
Before
json
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/{limit2}": {
"get": {
"parameters": [
{
"name": "limit2",
"in": "path",
"description": "max records to return",
"required": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
}
],
"operationId": "listVersionsV2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response"
}
}
}
}
},
"parameters": {
"limitParam": {
"name": "limit",
"in": "path",
"description": "max records to return",
"required": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
}
}
}
After
json
{
"swagger": "2.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"parameters": [
{
"name": "limit2",
"in": "query",
"description": "max records to return",
"required": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "multi"
}
],
"operationId": "listVersionsV2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response"
}
}
}
}
},
"parameters": {
"limitParam": {
"name": "limit",
"in": "path",
"description": "max records to return",
"required": true,
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"collectionFormat": "csv"
}
}
}