collectionFormat should support key[]=value

[Algiras]

Regarding joi not integrating delimeters https://github.com/hapijs/joi/issues/570 and https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md not supporting key[]=value. I would like to suggest adding this so it would be easy to use swagger-ui in more platforms that predefined key[]=value for array values. Currently I am using https://github.com/z0mt3c/hapi-swaggered. Hope you guys can help. If needed I can update the code myself. It's just adding one more way of parsing and adding more tests.

[webron]

It supports it already. Just give the parameter the name key[].

[Algiras]

The ui when generated with:

{
"required": false,
"collectionFormat": "multi",
"type": "array",
"items": {
"type": "string"
},
"name": "categories",
"in": "query"
}

generates request that sends

?categories=word&categories=otherWord

What I need is

?categories[]=word&categories[]=otherWord

[webron]

Right, so the generated name should be categories[] and not categories That's a problem with whatever is producing your definition, not the spec itself.

[Algiras]

I can make the tool generate name categories[]:

{
"required": false,
"collectionFormat": "multi",
"type": "array",
"items": {
"type": "string"
},
"name": "categories[]",
"in": "query"
}

the problem is that swagger-ui then encodes [] to categories%5B%5D.

Another big problem is semantics:

• when using no []
  • ?categories=word&categories=otherWord -> array of categories
  • ?categories=word -> single category as string(or predefined type)
• when using []
  • ?categories[]=word&categories[]=otherWord -> array of categories
  • ?categories[]=word -> array of categories with single value

Problem is swagger-ui can't differentiate, because it doesn't see the differences.

[webron]

As far as the ui encoding the square brackets, just open an issue on swagger-ui.

As for the difference in semantics, that's a tooling issue. We can't accommodate for every single variation a tool out there decides to use. Whether a single value, or an array of a single value, in most cases (I'm sure there are edge cases), those should mean the same thing (especially to an API consumer). Therefore, the ui doesn't need to differentiate as the meaning is pretty much the same.

[Algiras]

To create an issue I need to differentiate between parameters that can be either string or array via spec. Otherwise I have no ground rule for ui to differentiate.

[webron]

As long as you define the name as categories[] it should be sent as categories[] and not as categories%5B%5D. That has nothing to do with differentiating the logic. Other than that, I don't think there's anything to do with this issue as it is supported by the spec.

[jharmn]

Seems like there's quite a bit of overlap in #380, closing this we can carry on there. Please add any refinements you feel may have been missed.