Support all styles of Open API/swagger parameter serialization

[MikaelUmaN]

Is your feature request related to a problem? Please describe.

I would like to be able to choose what style to use for array parameters (and complex parameters in general) in Web Api methods.

https://swagger.io/docs/specification/serialization/

I want to be able to have comma-separated values, rather than ampersand concatenated. This prevents some APIs from becoming way to verbose and not user-friendly.

Describe the solution you'd like

Support for global conventions to use when serializing.
Support for local overrides of that convention via attribute annotations:

[FromQuery(style=form,explode=false)] int[] userIds

Then I can call the method using a URL containing: userIds=1,2,3

Above is for v3. For v2 the collectionFormat should be able to be declared for lists and arrays.

Describe alternatives you've considered

• Customized serialization. But if I customize, then I won't be able to use tool chains like NSwag to generate clients, and I won't get any leverage from my customization investment.

[pranavkm]

But if I customize, then I won't be able to use tool chains like NSwag to generate clients

I don't think either of the two OpenAPI toolchains we document and test against - NSwag or Swashbuckle - support the OpenAPI v3 spec. The v2 spec does not have a way to represent query string serialization format. Even if AspNetCore \ MVC added support for specifying the serialization format, your Swagger document wouldn't have a way to represent it.

[MikaelUmaN]

Under Array and Multi-Value Parameters you can see the v2 alternative of ”collection” style. Csv is the default but aspnet uses ”multi” with ampersands.

Why?

[RicoSuter]

NSwag already supports most of the OpenAPI 3 features, see RicoSuter/NSwag#945

[RicoSuter]

It would make sense to add this so that the model binder acts on it and the spec generators can read it via api explorer

[RicoSuter]

At the moment I think you have to customize the model binder and implement a custom nswag operation processor which correctly transforms the parameters...

[pranavkm]

You're right about the multi-value parameters, I missed that section of the spec. I've added it to our Swagger improvement tracking issue - #4854.

@Tratcher does AspNetCore support using commas as separator in query string?

[Tratcher]

No, just &
https://github.com/aspnet/AspNetCore/blob/ad8975001ae3eb5c63553e321c4069a190952f0b/src/Http/WebUtilities/src/QueryHelpers.cs#L151

[XomegaNet]

Btw, jQuery's param() method serializes arrays with square brackets by default (see examples below for versions >=1.4), which does not work with AspNetCore.

// <=1.3.2:
$.param({ a: [ 2, 3, 4 ] }); // "a=2&a=3&a=4"
// >=1.4:
$.param({ a: [ 2, 3, 4 ] }); // "a[]=2&a[]=3&a[]=4"

It would be great if AspNetCore supported that format as well. Note that it works fine in the old Web API for .Net Framework.

[mkArtakMSFT]

Thanks for contacting us, @MikaelUmaN.
We do not plan to provide customization for query string parameter separation.