Swagger-ui: Swagger UI doesn't seem to support Arrays yet?

[johnhamelink]

Hey there,

Please excuse my relative ignorance, I'm using Swagger within the context of a rails app and I'm not particularly up to date with where swagger's UI is in comparison with swagger's spec. I wanted to ask, has the UI implemented the Array type? I want to be able to define an API with parameters that would resolve to this in the API:

foo[]=1&foo[]=2&foo[]=3

In grape-swagger-rails I'm able to define a parameter as such:

requires :foo, type: Array[Integer], desc: 'An Array of Foos'

grape-swagger-rails (I think it's that gem which does this) renders the following JSON spec:

And Swagger UI renders the output like this:

When it queries the API, it generates the following url:

http://localhost/example?foo=1

Which of course works, but isn't helpful for allowing people to test.

[webron]

That's not the right definition for an array. You need to end up with something that looks like:

"type": "array",
"items": {
  "type": "integer"
}

[johnhamelink]

@webron thanks I'll try to get grape-swagger-rails to do that.

[fehguy]

Take a look here @johnhamelink :

https://github.com/swagger-api/rails-petstore

[exoszajzbuk]

I've done the following things:

1. Cloned the swagger-ui repo
2. Checked out develop_2.0
3. Opened dist/index.html

It is using http://petstore.swagger.io/v2/swagger.json by default, which has collectionFormat: "multi" set on pet/findByStatus.

If I understand it right, it should send the query parameters as tags=tag1&tags=tag2, if I enter a comma-separated string for the value. Instead it sends the parameters by simply encoding the comma.

[webron]

@exoszajzbuk - that's not really related to the OP. Can you open a separate issue for that?

[exoszajzbuk]

@webron opened as #987

[webron]

@exoszajzbuk - thank you!

[marcinskubala]

Hi, collectionFormat: "multi" should work with in="formData" too! Currently it works ony with in="query".

[fehguy]

Hi @marcinskubala I believe formData (x-www-form-urlencoded) has a standard for how multiple values are passed so a configuration shouldn't be necessary.

[marcinskubala]

Hi @fehguy, thanks for your answer, but I know the standards. For example:

{
    "name": "devices",
    "in": "formData",
    "type": "array",
    "items": {
        "type": "integer"
    },
    "collectionFormat": "multi"
}

I should be able in UI to put in devices fileld values: "1&2&3" or "1,2,3" and the post parameters should look like:
devices: 1
devices: 2
devices: 3
but currently it looks like "devices: 1,2,3"

[fehguy]

OK what you describe is a different issue. The question is "how do you enter multiple values in an array" and isn't related to formData. I think the right solution is to use a text edit box and newlines as delimiters rather than ampersands or other

[marcinskubala]

yep, the easiest way is to use a text edit box as you said or some cloning functionality but it will be more problematic so the edit box would be fine for me.

[webron]

@johnhamelink - any updates?

[johnhamelink]

@webron I never resolved this issue as other things became more important. I'll have another go this week and let you know my findings :smile:

[fehguy]

this should be fully supported now.

[splendf]

I have also an issue with the visualization of array model :

The swagger.json includes multiples references :

"parameters": [
  {
    "name": "body",
    "in": "body",
    "description": "Array of Values",
    "required": true,
    "schema": {
      "$ref": "#/definitions/values"
    }
  }
]
[...]
"values": {
    "type": "array",
    "items": {
        "$ref": "#/definitions/value"
    }
},
"value": {
    "properties": {
        "value": {
            "type": "object",
            "description": "Value stored. It could be a JSON object, JSON Array, string, boolean, integer, double, ...",
            "default": "any JSON objects or primitives (required)"
        },
        "location": {
            "type": "number",
            "format": "double",
            "minItems": 2,
            "maxItems": 2,
            "example": [
                48.870465,
                2.351447
            ],
            "description": "Location of the value. Latitude, Longitude"
        },
        "at": {
            "type": "string",
            "format": "date-time",
            "description": "Date of the value. <a href='http://www.iso.org/iso/home/standards/iso8601.htm'>Format ISO8601</a> <b>Ex. : 2014-06-16T14:25:08.017Z</b>"
        },
        "metadata": {
            "description": "Any custom couples of Key/Value",
            "$ref": "#/definitions/metadataOfValue"
        }
    }
},

It will be better if the documentation can display the array { values }, the structure of value and so on...
It is possible to do that with the current version ?

Thanks a lot

[webron]

Which version do you actually use?

[splendf]

2.1.5-M1

[webron]

Try the master version.

[splendf]

Indeed. Thx

[yuezhizizhang]

@webron How to specify a query parameter, which is an array of objects? Does it work?

"parameters": [
{
"name": "body",
"in": "query",
"description": "Array of Values",
"required": true,
"type": "array",
"items": {
"$ref": "#/definitions/value"
}
}
]
[...]
"value": {
...
}

[ryanackley]

I have just ran into this issue on master. Is it possibly a regression?

Swagger UI takes whatever I put into the text area and url encodes it into a single parameter. It should be multiple parameters with the same name. See screenshots below.

[fehguy]

What is your definition? I'm guessing you don't have the appropriate collectionFormat. Please open a new issue.

[leuchtdiode]

Another question regarding the collectionFormat:multi thing.

When I pass in an array like [ 0 => 'test1', 1 => 'test2' ] for the query parameter 'filter', the PHP client (especially http_build_query) makes this out of it:

filter=0=test1&1=test2

but it should be:

filter=test1&filter=test2

Any thoughts how I can prevent the array indices to be present in the string?