[develop 2.0] add support for multiple file uploads

[fehguy]

Per this discussion:

https://groups.google.com/forum/#!topic/swagger-swaggersocket/6a_tAGtj7CE

Would be helpful to add support for arrays of files. This would require updates in swagger-js as well.

[webron]

I think there's some confusion here. @mhdl64 is using Swagger 1.2 and not 2.0.

Another problem is that I can't think of a way to describe multiple file uploads, unless we modify the 2.0 spec.

You can describe a single file parameter, no problem. But you cannot specify an array of files, since file is not an applicable value for item's type - https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#itemsType.

We could change that, though it'll carry complications to both the documentation and the schema (not a reason not to add support for it).

Even if we do add support for it, we may need to impose a collectionFormat value of multi. It makes sense for multipart/form-data but possibly a bit less for application/x-www-form-urlencoded (though we can infer the meaning). We can say that the collectionFormat is inferred and with that combination it is assumed to be multi (and cannot be overridden - validation error), but we have a similar case in the spec where we currently force people to include a property with a known default value which cannot be changed.

Last thing, there's a ticket for a future version of the spec to allow specifying the mime type(s) of the uploaded files, and it should integrate well into this solution.

[fehguy]

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

looks appropriate but it's not supported. See here:
OAI/OpenAPI-Specification#254

[JanDintel]

@webron @fehguy I was able to work around the issue using a different name for the parameter object. So that the parameter is 'translated' to an Array.

Example:

The parameter files is an Array with uploaded files. Instead of using the parameter name "files", I used the parameter name "files[]". Thus resulting the following Swagger API specification:

{
  "path": "api/v1/upload",
  "operations": [
    {
      "summary": "Upload multiple files",
      "consumes": "multipart/form-data",
      "parameters": [
        {
          "paramType": "formData",
          "name": "files[]",
          "type": "file",
          "required": true
        },
        {
          "paramType": "formData",
          "name": "files[]",
          "type": "file",
          "required": false
        },
        {
          "paramType": "formData",
          "name": "files[]",
          "type": "file",
          "required": false
        },
        {
          "paramType": "formData",
          "name": "files[]",
          "type": "file",
          "required": false
        }
      ],
      "responseMessages": [
        {
          "code": 201,
          "responseModel": null,
          "message": "Created"
        },
        {
          "code": 422,
          "responseModel": null,
          "message": "Unprocessable Entity"
        }
      ],
      "method": "post",
      "nickname": "Api::V1::Uploads#create"
    }
  ]
}

Note:

I'm using a Rails backend and documented the API with the DSL of the swagger-docs gem.

[webron]

Technically, that's not a valid Swagger definition though.

[bytesandwich]

Maybe this could just be "allowMultiple" for files if the param is a form and ignore the param name?
If you're uploading an arbitrary number of files, I'm having a hard time seeing how you could give the notion of multiple files some sort of sane parameter name that is at all intuitive.

I'm just saying because my attempt to get multiple files to work was the same as Muhammad's from the google group post, so maybe other people are going to try the same thing first.

  @ApiOperation(
    httpMethod = "POST",
    nickname = "upload",
    value = "upload images")
  @ApiImplicitParams(
    Array(new ApiImplicitParam(
      name = "picture", // ignore this
      dataType = "file",
      paramType = "form",
      allowMultiple = true,
      required = true),

[webron]

Unfortunately, the current specification doesn't provide a way to solve it unfortunately. This is why there's an issue on swagger-spec about it linked above. allowMultiple won't work in this case.

[fehguy]

ok since this isn't supported by the spec, I'm going to close it.

[webermax]

@webron i assume @JanDintel's suggestion is not a valid definition because he repeats the same parameter name multiple times?

but there should be no problem to only use a single block

{
          "paramType": "formData",
          "name": "files[]",
          "type": "file",
          "required": true
}

only drawback i noticed so far is the file upload in the swagger gui does not support multiple files.

[webron]

@webermax the spec doesn't support a definition of a mulit-file parameter. You can define as many file parameters as you want, but you'd have to define the exact number of files.