The 'allowMultiple' ApiParam property doesn't appear in the JSON spec any more

[valdemon]

Hi,
I'm using the swagger-jaxrs_2.10:1.3.2 (with swagger-core_2.10:1.3.2) and experienced missing 'allowMultiple' attribute in the generated API JSON spec, when using the ApiParam(allowMultiple=true...) annotation.
The annotation attribute is not marked as deprecated. Is it missing in JSON by intention (eg. because being redundant as of usage of the 'array' type) or is it a bug?

[webron]

Using allowMultiple and an array value type are mutually exclusive. Do you
experience the same problem with types that are not array?

To be clear, 'allowMultiple`suggest a different way to pass multiple values
than an array does.

On Wed, Mar 5, 2014 at 11:59 AM, valdemon [email protected] wrote:

Hi,
I'm using the swagger-jaxrs_2.10:1.3.2 (with swagger-core_2.10:1.3.2) and
experienced missing 'allowMultiple' attribute in the generated API JSON
spec, when using the ApiParam(allowMultiple=true...) annotation.
The annotation attribute is not marked as deprecated. Is it missing in
JSON by intention (eg. because being redundant as of usage of the 'array'
type) or is it a bug?

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/478
.

[valdemon]

I've been using the 'allowMultiple' since the swagger-core 2.9.x.
For now, i can't find anything about this attribute in the Wiki: https://github.com/wordnik/swagger-core/wiki/Parameters, and there's a statement there: "When sending multiple values, the array type should be used".
When using the swagger-jaxrs lib, in cases that the List or Type[] is used for the JAXRS service method query param, the 'array' type is declared in the generated JSON spec. (which is fine), but the 'allowMultiple' is not there any more (as it was there before - in 2.9.x, i guess), when declared in ApiParam annotation.
Probably making assumptions using the 'allowMultiple' in this case was my mistake. Actually the 'array' type is enough to assume that the multiple values can come.
Above concerns the issue swagger-api/swagger-ui#304, where the 'allowMultiple' attr was inspected. I decided to change that functionality and use the 'array' type check instead. Just wanted to know if the 'allowMultiple' is kinda deprecated..
I can't find any documentation about the 'allowMultiple' definition & use cases. Could you provide an example when this attribute could be used for non-array param cases?

[webron]

Let's try and organize a few things - I completely understand why the
current state may be confusing (which is why we're rewriting the
documentation).

First off, swagger-core never had a 2.9.x version. The 2.9.x vs 2.10.x in
the library name denote the Scala version that was used to compile the code
(that is, 2.9 vs 2.10). Current swagger-core version is 1.3.2/1.3.3.

That said, the current Swagger-Core version supports Swagger Spec version
1.2 I am not familiar with the history of all changes that were made over
time in the spec, and it's possible that allowMultiple was used initially
over an array value.

allowMultiple is currently not deprecated, but may change in functionality
in future spec versions.

An array would lead to a value in the format of [value1, value2, value3].
'allowMultiple', when used in a query parameter, would lead the values
being coma separated, so that the url would look like
http://path/to/resource?paramName=value1,value2,value3.

So while both allow multiple values, the way they are used is a bit
different. Does this clear things up?

On Wed, Mar 5, 2014 at 4:30 PM, valdemon [email protected] wrote:

I've been using the 'allowMultiple' since the swagger-core 2.9.x.
For now, i can't find anything about this attribute in the Wiki:
https://github.com/wordnik/swagger-core/wiki/Parameters, and there's a
statement there: "When sending multiple values, the array type should be
used".
When using the swagger-jaxrs lib, in cases that the List or Type[] is used
for the JAXRS service method query param, the 'array' type is declared in
the generated JSON spec. (which is fine), but the 'allowMultiple' is not
there any more (as it was there before - in 2.9.x, i guess), when declared
in ApiParam annotation.
Probably making assumptions using the 'allowMultiple' in this case was my
mistake. Actually the 'array' type is enough to assume that the multiple
values can come.
Above concerns the issue swagger-api/swagger-ui#304swagger-api/swagger-ui#304,
where the 'allowMultiple' attr was inspected. I decided to change that
functionality and use the 'array' type check instead. Just wanted to know
if the 'allowMultiple' is kinda deprecated..
I can't find any documentation about the 'allowMultiple' definition & use
cases. Could you provide an example when this attribute could be used for
non-array param cases?

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/478#issuecomment-36747015
.

[valdemon]

Ok, thanks for clarifying that.
How should the example request URL look like, when using the 'array' type for the query parameter? Could you please align this somehow with the discussions @ swagger-api/swagger-ui#118 ?

[webron]

That actually depends on the mime-type the application consumes. Assuming
JSON, it would look like
http://path/to/resource?paramName=[value1,value2,value3]
Personally, I would avoid using an array of values in a query parameter
as the value would also need to be URL encoded. That said, it doesn't mean
it's not possible.

I can't really comment regarding the open Swagger-UI issue.

On Wed, Mar 5, 2014 at 5:40 PM, valdemon [email protected] wrote:

Ok, thanks for clarifying that.
How should the example request URL look like, when using the 'array' type
for the query parameter? Could you please align this somehow with the
discussions @ swagger-api/swagger-ui#118swagger-api/swagger-ui#118?

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/478#issuecomment-36754938
.

[valdemon]

hmm, now i'm really confused.
As far as I know, the mime-type (or Content-type header) concerns the BODY part of the request not the query params.
Maybe i'll describe my use case:

1. Using the JAXRS implementation I declare the REST service with a GET method, which takes the array (or java.util.List) of primitives (eg Integers) annotated with swagger's ApiParam.
2. swagger-jaxrs 'DefaultJaxrsApiReader' generates the JSON spec with the parameter of the 'array' type by automation in such a case.
3. JAXRS implementation converts & injects the request parameter automatically to the array or List method parameter as long as the request query is in a format like '...&param=value1&param=value2...'.

As the No.3 is kinda standard for the JAXRS reference implementations, and the request query syntax: '...param=value1&param=value2...' is the most used "standard", i'd like to have an interactive REST documentation, which produces the request in an expected by the REST service way, from some friendly UI (comma separated string in a textbox, multi-select list box etc.). But that's rather swagger-js & swagger-ui related (I've put some propositions for that with my latest pull requests).

The 'allowMultiple' seems to be superfluous in my use case. Question is if there's really a use case, which fits for using this attribute (especially in case of query params)?

[webron]

Okay, I may have got it wrong regarding how it would work with query
params, and your sample makes sense. Keep in mind that with primitives that
would be easy, but with complex models, that's where it'd get more
complicated (hence the mime types, since the models need to be
de/serialized somehow).

I can't really give you an actual use case for the use of 'allowMultiple',
however the swagger-ui issue you previously linked to shows some samples
that may be relevant/common with other frameworks.

On Wed, Mar 5, 2014 at 6:36 PM, valdemon [email protected] wrote:

hmm, now i'm really confused.
As far as I know, the mime-type (or Content-type header) concerns the BODY
part of the request not the query params.
Maybe i'll describe my use case:

1. Using the JAXRS implementation I declare the REST service with a GET
   method, which takes the array (or java.util.List) of primitives (eg
   Integers) annotated with swagger's ApiParam.
2. swagger-jaxrs 'DefaultJaxrsApiReader' generates the JSON spec with the
   parameter of the 'array' type by automation in such a case.
3. JAXRS implementation converts & injects the request parameter
   automatically to the array or List method parameter as long as the request
   query is in a format like '...&param=value1&param=value2...'.

As the No.3 is kinda standard for the JAXRS reference implementations, and
the request query syntax: '...param=value1&param=value2...' is the most
used "standard", i'd like to have an interactive REST documentation, which
produces the request in an expected by the REST service way, from some
friendly UI (comma separated string in a textbox, multi-select list box
etc.). But that's rather swagger-js & swagger-ui related (I've put some
propositions for that with my latest pull requests).

The 'allowMultiple' seems to be superfluous in my use case. Question is if
there's really a use case, which fits for using this attribute (especially
in case of query params)?

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/478#issuecomment-36762615
.

[fehguy]

@valdemon allowMultiple is intended to support passing multiple values for the same parameter--for instance, a query param:

foo=a,b,c,d

if you're looking for this:

foo=a&bar=b

as query params, you don't need to pass it.

Regarding the format for the first case, there is no standard, only convention, and that varies wildly between formats, servers, developers and the phase of the moon. We're adding a format parameter to allow that to be described, which should end the chaos.

[valdemon]

@webron: true, but i wouldn't expect complex types to be a standard approach for query parameter values, although it is possible with some de/serialization using mime type like JSON (maybe + Base64 encoding), as you pointed. And still possible to bind it to the array or collection of such a complex type as a method parameter eg. in JAXRS impl.

@fehguy:

foo=a&bar=b

is out of the scope of this discussion.
I was thinking of:

foo=a&foo=b&foo=c

instead of

foo=a,b,c

which would do for my case (Java & JAXRS reference implementations).
But the format parameter seems to be The Solution, because, as you pointed, there's no standard for multiple values query parameter (eg. RoR doesn't understand my desired syntax).
If i'd be aware of the format parameter i'd take it under account when preparing the swagger-api/swagger-js#83 (if it is ready to use).

Anyway - the main questions - still not answered - were:

1. Will the 'allowMultiple' attribute stay in the specification?
2. Isn't it just superflous for the 'array' type in case of the query parameters?
3. What is a use case for it?
4. To what structure will it cause to convert the multiple value parameter, if not to array or collection (in which case eg. the swagger-jaxrs generates the 'array' type parameter).

Feel a bit like bothering you, but i'd like to understand your intention in this subject, and decide what to do with my use case.

[fehguy]

Hi, @valdemon thanks for following up. I think the correct course of action is to change the specification to support the array type, add a format attribute, and get rid of the allowMultiple syntax.

In the mean time, the allowMultiple will remain, for query parameters, until the 2.0 spec. I believe having a @QueryParam annotation with type List would allow swagger to auto-detect and generate the right structure for the 2.0 spec. I think we can nudge in a format param now, since it is non-breaking for the spec, and will solve the immediate need.

The current UI will turns the values into a CSV string. Again, not ideal.

[valdemon]

Hi,
concerning the CSV - maybe it's not bad to have it as a first format produced by the UI elements (eg, writing the value set as CSV in a text box is more convenient than in any syntax like _x=a&x=b).
Then one could change outgoing value to a choosen format at the place where the query param values are urlified, like I did in swagger-api/swagger-js#83, which could be enhanced for taking the _format param into account.

[fehguy]

Hi folks, allowMultiple is back as of 1.3.3-SNAPSHOT and we'll support a format syntax shortly.

[brutuscat]

@fehguy I know that this is closed and in our project we are in the path to migrate to swagger v2 (json schema yay!), but apart from the comma-separated value format, you might also considerthe, already supported by php and ruby (and I guess more languages), key[]=value format.

[webron]

@brutuscat - that's a naming convention, not a value one. By default, JAX-RS will use multiple instances of the same name (so key=X&key=Y). If you want to end up with key[]=value you'd have to make sure to translate that to the parameter name as well.

[brutuscat]

@webron JAX-RS is also a naming convention, that's what are you saying right? I understand that, I was just suggesting to not forget this particular format when considering formats. TBH honest haven't read the whole thread...

Ok, but what about try to use some sort of RFC 6570 - URI Template to specify the format? No idea if it is possible to have template "fragments" though...

[webron]

@brutuscat - this project is about Java in general and JAX-RS more specifically right now (with some support for other frameworks). It doesn't need to support conventions that don't exist here.

As for URI templating, that's an entirely different issue that's been discussed in our google groups and swagger-spec repo several times. Please try to look those up.

[brutuscat]

@webron right! I guess "core" and "spec" looks similar to me... I'll read the discussion in the groups thanks.

[DavidBiesack]

OpenAPI 2.0 does not support allowMultiple, nor does it allow format: array. However, one can set the type of a query parameter to array (with items being a string/enum) and set collectionFormat: csv, and Swagger UI will emit

 … &param=value1,value2

OAS 3.0 will allow parameter styles which includes a style: form, explore:false style for query params which should support the same csv representation.