How to post files in Swagger (OpenAPI)?
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
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: