76

I am using Swagger to document my REST services. One of my services requires a CSV file to be uploaded. I added the following to the parameters section in my JSON API definition:

{
       "name": "File",
       "description": "The file in zip format.",
       "paramType": "body",
       "required": true,
       "allowMultiple": false,
       "dataType": "file"
}

and now I see the file upload option on my Swagger UI page. But when I select a file and click "try it out", I get the following error:

NS_ERROR_XPC_BAD_OP_ON_WN_PROTO: Illegal operation on WrappedNative prototype object in jquery-1.8.0.min.js (line 2)

The page is continuously processing and I am not getting any response.

Any ideas what could be wrong?

Helen
  • 87,344
  • 17
  • 243
  • 314
CodeGuru
  • 2,722
  • 6
  • 36
  • 52
  • can you try it without the last comma behind "file"? – Sebastian Stiehl Feb 01 '13 at 13:25
  • @Soc : Please ignore that comma, it is just a typo mistake. – CodeGuru Feb 05 '13 at 07:03
  • maybe you can try to debug this the following way: (maybe use newer query version), use a not-minimized version of jquery and take a look into JS console (maybe set a breakpoint) and find out how the error is produced. Maybe you'll get more information about what causes the problem. – mr.VVoo Feb 20 '13 at 16:40

4 Answers4

112

OpenAPI Specification 2.0

In Swagger 2.0 (OpenAPI Specification 2.0), use a form parameter (in: formData) with the type set to file. Additionally, the operation's consumes must be multipart/form-data.

  consumes:
    - multipart/form-data
  parameters:
    - name: file
      in: formData   # <-----
      description: The uploaded file data
      required: true
      type: file     # <-----

OpenAPI Specification 3.0

In OpenAPI Specification 3.0, files are defined as binary strings, that is, type: string + format: binary (or format: byte, depending on the use case). File input/output content is described with the same semantics as any other schema type (unlike OpenAPI 2.0):

Multi-part request, single file:

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          # 'file' will be the field name in this multipart request
          file:
            type: string
            format: binary

Multi-part request, array of files (supported in Swagger UI 3.26.0+ and Swagger Editor 3.10.0+):

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          # The property name 'file' will be used for all files.
          file:
            type: array
            items:
              type: string
              format: binary

POST/PUT file directly (the request body is the file contents):

requestBody:
  content:
    application/octet-stream:
      # any media type is accepted, functionally equivalent to `*/*`
      schema:
        # a binary file of any type
        type: string
        format: binary

Note: the semantics are the same as other OpenAPI 3.0 schema types: 

# content transferred in binary (octet-stream):
schema:
  type: string
  format: binary

Further information:

Helen
  • 87,344
  • 17
  • 243
  • 314
mstrthealias
  • 2,781
  • 2
  • 22
  • 18
  • 2
    How does one access the file in the node js controller? like if my file is called `filedata`, then my instream variable should be initialized to something like `req.swagger.params.filedata.value`? that gives me an error. – FaultyProgrammer3107 Mar 29 '17 at 20:24
  • Can you please explain why the swagger OpenAPI specification is not pointing that out? https://swagger.io/specification/#considerations-for-file-uploads-61 – AmazingTurtle Jan 18 '18 at 18:29
  • @AmazingTurtle You linked to OpenAPI specification 3.0; I've updated the answer to include OpenAPI spec 3.0. – mstrthealias Nov 06 '18 at 16:57
  • Can you explain more, e.g: when i use Django rest framework which module of code should be modified? thanks! – joe-khoa Aug 07 '20 at 10:17
  • https://stackoverflow.com/questions/71519777/multipart-file-upload-using-springfox-and-swagger-ui-upload-is-not-working – Smart Coder Oct 18 '22 at 19:46
19

finally i found answer for this, actually previously there is no support for file upload, now they updated swagger-ui.js file. You need to replace your old one with new and also you have to define these properties under Parameters for particular parameter: 

 "paramType": "body",
 "dataType": "file",
CodeGuru
  • 2,722
  • 6
  • 36
  • 52
  • 3
    This answer is for an older version of Swagger Specification (1.x?) and won't work in OpenAPI 2.0 / OpenAPI 3.0. See [mstrthealias' answer](https://stackoverflow.com/a/37932354/113116) instead. – Helen Apr 15 '19 at 12:50
4

Mine seems to work with

 "paramType": "formData",
 "dataType": "file",
Artjom Kurapov
  • 6,115
  • 4
  • 32
  • 42
  • 1
    This answer is for an older version of Swagger Specification (1.x?) and won't work in OpenAPI 2.0 / OpenAPI 3.0. See [mstrthealias' answer](https://stackoverflow.com/a/37932354/113116) instead. – Helen Apr 15 '19 at 12:50
3

I am using Open API v 3.0.3

Here's what my swagger.json looks like:

"/media/upload": {
      "post": {
        "tags": ["Media"],
        "name": "Upload Media",
        "description": "Uploads a Media file to the server.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "media": {
                    "type": "string",
                    "format": "base64"
                  }
                }
              }
            }
          }
        }
      }
    }

Here's how it shows up in swagger:

enter image description here

Hamza Azad
  • 2,637
  • 1
  • 20
  • 15