Openapi-specification: Add support for query param array format

[fehguy]

There is no standard for handling arrays as query parameters. We should be able to add a format structure to let the API server specify what it expects, and have swagger-js + codegen produce the correct structure.

[stuartbuckell]

+1

[webron]

I believe #34 is related.

[maxymajzr]

Would there be anything wrong if we could specify an array as a form parameter as well? I am unsure why it doesn't exist since I started using swagger only a few days ago, but not being able to specify an array parameter that I can send either trough POST body or GET querystring is a bit of a show stopper.

[webron]

Why do you say you can't specify an array as a form parameter?

On Thu, May 8, 2014 at 5:42 PM, Nikola B. [email protected] wrote:

Would there be anything wrong if we could specify an array as a form
parameter as well? I am unsure why it doesn't exist since I started using
swagger only a few days ago, but not being able to specify an array
parameter that I can send either trough POST body or GET querystring is a
bit of a show stopper.

—
Reply to this email directly or view it on GitHubhttps://github.com/wordnik/swagger-spec/issues/49#issuecomment-42558055
.

[maxymajzr]

Ok, I might be wrong so please correct me if that's the case, but I wasn't able to find how to define the parameters object that would allow me to produce the following request (going to paste raw HTTP request to illustrate the problem better):

POST /my/route/ HTTP/1.1
Host: my.host.web
Connection: keep-alive
Content-Length: 64
Accept: application/json
Origin: http://my.host.web
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/34.0.1847.131 Safari/537.36
Content-Type: application/x-www-form-urlencoded
Referer: http://my.host.web/
Accept-Encoding: gzip,deflate,sdch
Accept-Language: en-GB,en;q=0.8,en-US;q=0.6,hr;q=0.4,sr;q=0.2

param[]=1&param[]=2&param[]=3&next_value=lorem&other_value=ipsum

[darrentaytay]

@Majeh, did you find out how to specify an array in a form param?

[maxymajzr]

@dtisgodsson - no, I haven't found out how to do it so it can produce the array as specified in my previous comment. Maybe @webron can share his thoughts on the matter.

[webron]

@Majeh - feel free to correct me if I'm wrong, but it looks like the HTTP request you posted sends parameter as part of the body and not as query parameters.

[maxymajzr]

@webron - yes, it's a part of the body, however the same parameters can be sent via query as well. At this point, I'd be happy with being able to specify an array "manually" in the format described previously. If there is something like that in the docs please do point me, I might have missed it while reading it through.

[webron]

Okay, I just re-read your comments. So let's try to clarify.
Swagger supports 5 parameter definitions - body, query, path, form and header (https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md#524-parameter-object).
Any of those can be defined as an array (at least in theory), and some also offer the 'allowMultiple' as an alternative way to pass on an array of elements (this would change in a future version of the spec).

That said, I have no experience personally with form parameters, and as such, I admit I'm not certain what would be the expected usage of a form parameter that's defined as a type of array. @fehguy should be able to elaborate more on that.

[maxymajzr]

@webron - after trying out the body parameter I noticed I can manually specify an array in the format previously mentioned (for some reason I was sure that body parameter will name the parameter in the payload, not replace the payload entirely), which lets me continue to use swagger for testing REST APIs. I must admit I didn't go in depth so I can't tell if there are any further problems, but basically I've done this to define parameters:

"parameters": [    
    {
        "name": "not_relevant",
        "description": "A raw definition of payload",
        "required": false,
        "type": "string",
        "paramType": "body"
    }
]

That renders the textarea that allows me to define a "raw" payload which is what I wanted. As for sending the array trough the query - I gave up on that for the moment.

However, the solution above forces me to manually type out the entire payload, instead using swagger's parameters object to be able to send more data through.

What I basically want to highlight is that if I want to send say username and password through a form, and I need to send an array of data (let's say emails[]) - I've to manually construct the request payload.
There's no way to specify the imaginary username and password parameters and then concatenate it with the body, which would produce something like:
username=test&password=hello&email[]=first&email[]=second

I do realize it's difficult to implement and I can work with the solution I mentioned. What this entire post was about was me asking - is the right method to specify the entire payload manually or does there exist something that lets me specify an array of values (not comma separated) along with some arbitrary parameters?

[webron]

Okay, I've read about it a bit.
What you should use is something like this:

"parameters": [    
    {
        "name": "not_relevant",
        "description": "A raw definition of payload",
        "required": false,
        "type": "array",
        "items": {
            "type": "string"
        },
        "paramType": "form"
    }
]

Keep in mind that when you do that, the "consumes" of the operation has to be application/x-www-form-urlencoded.
This _should_ work, however, Swagger-UI may not support it (I'll leave it for you to test it at the moment). In terms of having a field in the UI form per field described here, it would work. How it would handle array/multiple values, I'm not sure.

[maxymajzr]

@webron - thanks for the suggestion, I'll use it as soon as work schedule frees up and will update with what I've tried and how it turned out.

[webron]

This has been resolved in Swagger 2.0 with the collectionFormat property.

[kiaplayer]

@webron
So, how can I describe such parameter: ?fields[]=number&fields[]=date_time&fields[]=... ?

[webron]

That's a query parameter that has a collectionFormat of multi and its name is fields[] (notice the square brackets are part of the name). Does that help?

[kiaplayer]

@webron
It doesn't work with swagger-ui 2.1.0-alpha.1.
Brackets in fields names are encoded anyway and there is no way to set such values for "Try it".
But I think it's swagger-ui issue.
Thanks.

[fehguy]

Can you please file an issue in swagger ui?

[kiaplayer]

@fehguy
There ase similiar issues already:
wordnik/swagger-ui#118, wordnik/swagger-ui#657, wordnik/swagger-ui#635.

[webron]

@kiaplayer - those are actually different issues.
https://github.com/wordnik/swagger-ui/issues/118 and https://github.com/wordnik/swagger-ui/issues/657 are general about multi support but not about the brackets in the parameter name.
https://github.com/wordnik/swagger-ui/issues/635 relates to brackets in the path, not in parameter names.
So it would still be useful if you can open an issue specifically about the brackets in the parameter name.

[kiaplayer]

@webron
Okey, wordnik/swagger-ui#661

[webron]

@kiaplayer - thank you for taking the time.

[fehguy]

@webron I think we're missing two collectionFormat values in the spec. Many frameworks want this:

a=1&a=2&a=3

to represent a list a with values (1,2,3). This includes jaxrs, and you're describing multi in this ticket which isn't actually in the spec right now (that I see).

Similarly, many frameworks want the brackets in the name like in this initial issue, and it seems like this might be a named format, like brackets or something. Would make life much easier in the js library, since we don't need to handle special characters in the parameter name (the brackets will be encoded by default):

https://github.com/wordnik/swagger-js/blob/develop_2.0/src/main/javascript/swagger.js#L624

[webron]

multi is described in the spec and the schema - https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md#parameterCollectionFormat with a few restrictions (it's only relevant in query and formData params).

I think you need to handle special characters in the name one way or another. What if someone decides to name their parameter api-key? Or have some accented letters in the parameter name? Wouldn't all those cause issues as well? I can add it, of course, it just feels like we're dealing with an edge case rather than the problem as a whole.

[packpaul]

Hi! I've also had recently a problem representing this:
productID1=1&productID2=2&...
I'm rewriting a hand-written API spec. as swagger.yaml

[ePaul]

@packpaul that URI syntax can't be represented in OpenAPI (neither in version 2.0 nor what is currently proprosed in 3.0, as far as I understand).

[packpaul]

I didn't know it. So here's a proposal to implement it in the following version.

[ePaul]

Please open a new issue (with a more detailed proposal how you imagine it to be represented). Commenting on closed issues doesn't help.

[Download]

the brackets will be encoded by default

Isn't this the bug?
Encoding characters that need not be encoded is just... wrong is it not?

[aleksbrgt]

Brackets in fields names are encoded anyway

Isn't this the bug?
Encoding characters that need not be encoded is just... wrong is it not?

Actually, the encoded brackets work (at least with PHP), so ?array[]=1&array[]=2 is the same as ?array%5B%5D=1&array%5B%5D=2