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

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?

You are generating an OpenAPI 2.0 definition. 2.0 does not support objects (incl. dictionaries) in the query string. It's supported in OpenAPI 3.0 though. Does Swashbuckle support OpenAPI 3.0? — Helen, Apr 18 '18 at 12:25
Thanks @Helen, was not aware. I will follow this issue https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/671 Please make your comment an answer, and I'll accept it — Magnus Johansson, Apr 20 '18 at 09:18

Helder Sepulveda · Answer 1 · 2018-04-18T13:31:33.100

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

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

1 Answers1