How to make Swashbuckle generate correct OpenAPI schema for a Dictionary parameter? - swashbuckle

Question

I have an ASP.NetCore action method that is defined as:
[HttpGet]
public async Task<IActionResult> Get([FromQuery]Dictionary<string,string> values)
{
return Ok(JsonConvert.SerializeObject(values));
}
The expected query would be something like:
http://localhost:36541/api?values[someProperty]=123&values[someOther]=234
When I use Swashbuckle the resulting swagger.json file would end up like:
{
"swagger": "2.0",
"info": {
"version": "v1",
"title": "Test API"
},
"paths": {
"/api/Api": {
"get": {
"tags": [
"Api"
],
"operationId": "ApiApiGet",
"consumes": [],
"produces": [],
"parameters": [{
"name": "values",
"in": "query",
"required": false,
"type": "object"
}],
"responses": {
"200": {
"description": "Success"
}
}
}
}
},
"definitions": {}
}
But this doesn't validate using autorest or http://editor.swagger.io/
The error is:
Schema error at paths['/api/Api'].get.parameters[0]
should NOT have additional properties
additionalProperty: type, name, in, required
Jump to line 14
Schema error at paths['/api/Api'].get.parameters[0].required
should be equal to one of the allowed values
allowedValues: true
Jump to line 14
Schema error at paths['/api/Api'].get.parameters[0].in
should be equal to one of the allowed values
allowedValues: body, header, formData, path
Jump to line 15
Schema error at paths['/api/Api'].get.parameters[0].type
should be equal to one of the allowed values
allowedValues: string, number, boolean, integer, array, file
Jump to line 17
It seems that it's missing the additionalProperties property according to https://swagger.io/docs/specification/data-models/dictionaries/
How can I make this query parameter be a valid OpenAPI / Swagger definition?

Answer 1

Following up on the comment from #Helen
Swashbuckle does not support the OpenAPI Specification (OAS) 3.0 yet, so you should not have objects (such as dictionaries) on the query string.
My recommendation change that action to a Post and get the values from the Body, also since your response is IActionResult consider using SwaggerResponse something like this:
[HttpPost]
[SwaggerResponse(200, typeof(Dictionary<string, string>), "This returns a dictionary.")]
public async Task<IActionResult> Post([FromBody]Dictionary<string,string> values)
{
return Ok(JsonConvert.SerializeObject(values));
}
Update:
I was also looking into the possibility of sending the GET with a body, and there seems to be a lot of debate about it:
HTTP GET with request body