How to post files in Swagger (OpenAPI)?

Question

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?

Answer 1

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:

• Considerations for File Uploads
• Special Considerations for multipart Content
• File Upload and Multipart Requests