Openapi-specification: enable multiple file support?

[fehguy]

While not explicitly allowed, it seems we might want to enable type: file inside arrays to allow for support of multiple files.

[JamesMessinger]

Can't you already accomplish this by simply having more than one parameter with {type: "file"}? As long as your Content-Type is multipart/form-data, you can send multiple files in a single request.

Or am I missing something?

[webron]

@BigstickCarpet - the idea is to allow an undefined number of files to upload. You can set several individual parameters but that's not quite the same.

[JamesMessinger]

Ah, ok. :+1:

[bytesandwich]

Any thoughts on this? multiple file upload (where the user decides how many files to upload) seems like a really common use case.
Enough that dropzone has nearly 8,000 stars https://github.com/enyo/dropzone

[webron]

So following #50, we may be able to allow the declaration of an array of "type": "string", "format": "binary" as a workaround for multiple file upload definitions.

[Hronom]

Any progress on this?

[fehguy]

Most likely part of 3.0

[akkie]

Currently this should be possible with:

- name: files
  in: formData
  description: Upload multiple files
  required: true
  type: array
  items:
    type: File
  collectionFormat: multi

If the documentation could be adapted to:

corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz. This is valid only for parameters in "query" or "formData". For files in "formData" an numeric index will be appended to the parameter name (files0, files1, ...).

[darrelmiller]

A new approach has been introduced in the V3 spec to model multi-part forms included files. The type: file has been removed because it is not valid in JSON Schema. Also, request bodies are no longer modeled as parameters.

[ePaul]

@darrelmiller Are you meaning to say that uploading e.g. an array of files is now possible?

I guess the explode property of encoding can help here, thought I'm not sure this is the correct way of doing this:

requestBody:
  content:
    multipart/mixed:
      schema:
        type: object
        properties:
          id:
            # default is text/plain
            type: string
            format: uuid
          address:
            # default is application/json
            type: object
            properties: {}
          profileImages:
            # default is application/octet-stream, need to declare an image type only!
            type:array
            items:
              type: string
              format: binary
      encoding:
        profileImages:
          # only accept png/jpeg
          contentType: image/png, image/jpeg
          style: form
          explode: true

How would the form images be named in the request? profileImages[0], profileImages[1], ...?
I guess this needs some clarification (and an example) in the spec.

[darrelmiller]

I know we discussed this scenario and it was intended to support it. I don't believe style needs to be used here because style is a serialization hint and binary streams of images are not going to be encoded with key value pairs. As for how the naming of the parts is defined, I'm not sure, but your suggestion does make sense.

We got to a point with the definition of the multi-part stuff where we felt we needed to actually try implementing some of the scenarios before we rat-holed on trying to get the definition airtight.

[webron]

We should have made it clearer in the spec - iirc, style and explode are both only relevant when the media type is application/x-www-form-urlencoded.

As for the naming, what @darrelmiller said.

[tuxedo0801]

Any progress on this? Open since ~3yrs and counting ...

[vdachev]

@tuxedo0801 , actually OpenAPI 3.0 supports defining multi-file upload.

• Swagger Editor supports OpenAPI 3.0 on its editor part.
• However Swagger UI has to catch up and you can follow swagger-api/swagger-ui#3641 (referenced by swagger-api/swagger-ui#4276).
• You can also follow the list of implementation.

[iwt-nduesing]

This seems to be the same issue: OAS 3: Support for uploading an array of files in multipart requests #4600

[mightymercado]

I made a quick dirty fix for this issue in my fork:

I think swagger-client in general does not support multiple files, so the fix needs to start from there. I'll work on this soon.

[Cloudmersive]

This is so basic. Can you guys implement it? The incompleteness of OpenAPI 2 vs. HTTP features is a real pain point. IT's not optional to support all the features of HTTP

[handrews]

@Cloudmersive OpenAPI 2 is no longer under active development so the solution here is to move to OpenAPI 3.

@darrelmiller @webron is there any reason to keep this open?

Per https://github.com/OAI/OpenAPI-Specification/issues/254#issuecomment-412306495 it's solved in OAS 3.0, and the rest of the links and comments here are about tooling support or OAS 2.0

Also, is there an official statement that OAS 2 is no longer in active development? I couldn't find one offhand but I know it's been said somewhere.

[darrelmiller]

Yeah, I think with a bit of creativity you can describe this scenario with OpenAPI V3. I'm ok with closing this and let some open an new issue if they find there is something they cannot do.

There is no more work on-going on OpenAPI V2.