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?
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
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",
Mine seems to work with
"paramType": "formData",
"dataType": "file",
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:
Related
I was trying to add a file upload option for a POST request in Swagger UI by following the documentation.
The problem is this:
As you can see, Swagger UI does not render anything, neither for textual inputs nor for file inputs.
I tried to search on SO other answers about this but nothing.
This is the request body that I defined for the requestBody parameter of the path:
CreateTicketMessagePayload:
description: |-
Request multipart body required to proceed in the ticket message creation processes.
**Object part**:
```
{
"message": "Textual content of the message",
"private": "Flag that indicates the message is visible just for technicians"
}
```
**File part**:
"attachment": Message attachment file.
content:
multipart/form-data:
schema:
type: object
properties:
message:
type: string
example: This is a message
private:
type: boolean
example: false
attachment:
type: string
format: binary
What am I doing wrong?
In case of multipart/form-data requests, Swagger UI shows the inputs after you click "Try it out".
There's an existing enhancement request to display the inputs by default:
Display static documentation information for multipart properties in OpenAPI 3.0 files
I have an ASP.NET Core 6 Web API project with swagger configured. One of the operation endpoints accepts a file as [FromForm] IFormFile file
For that parameter swagger generates the following schema:
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
}
}
I then use swagger-codegen to generate typescript client. However, codegen requires files to be declared as:
parameters:
- in: formData
name: upfile
type: file
description: The file to upload.
Question: how do I configure swagger in my ASP.NET Core 6 Web API project to emit file operation parameter with type file instead of type object?
Say I have an OpenAPI swagger.yml file that looks like:
openapi: '3.0.2'
info:
title: Simplest ever
version: '1.0'
servers:
- url: https://api.server.test/v1
paths:
/test:
get:
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
message:
type: string
I prefer to keep the source of truth schema in my schemas/ directory, for example schemas/get.json looks like:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
The intent is for the schemas/*.json to used in my backend code base for validation for incoming and outgoing messages. Goal is to have strong API contracts.
What I don't understand is how to build the swagger.yml file using these JSON schema, instead of duplicating the work in YAML which is really tedious and error prone.
In OpenAPI 3.1, you can reference your JSON Schemas directly:
# openapi: 3.1.0
content:
application/json:
schema:
$ref: 'schemas/get.json'
Earlier OpenAPI versions expect that the JSON Schemas be converted to the OpenAPI Schema Object format (which can be represented as both YAML and JSON). The necessary changes include, for example:
removing unsupported keywords: $schema, patternProperties, and others;
replacing type: [<foo>, 'null'] with type: <foo> + nullable: true;
replacing other type arrays type: [type1, type2, ...] with oneOf/anyOf (OAS3) or removing them (OAS2).
json-schema-to-openapi-schema can automate the conversion.
You can try to $ref vanilla JSON Schemas directly from OAS 2.0 and 3.0 definitions, but some tools will error out on unexpected keywords and constructs.
I want to upload image file.
Swagger 2.0 code for upload
/upload:
post:
summary: Uploads a file.
consumes:
- multipart/form-data
produces:
- application/json
parameters:
- name: image
in: formData
required: false
type: file
description: The file to upload.
responses:
'200':
description: OK (successfully uploaded)
'500':
description: Error importing file
I am testing this through postman were in body I have mentioned "form-data"
key: "image" value :"Image file"
I am receiving following error
{
"statusCode": 400,
"error": "Bad Request",
"message": "child \"image\" fails because [\"value\" must be a string]",
"validation": {
"source": "payload",
"keys": [
"image"
]
}
}
Currently my swagger output as a body parameter that looks like this
{
"name": "body",
"in": "body",
"description": "",
"required": true,
"type": "file"
}
and i read the documentation that the type property can be a array of types
{
"name": "body",
"in": "body",
"description": "",
"required": true,
"type": [null,"file"]
}
but I have found no way to tell aspnet core mvc or swaggerGen to output two types? Is this possible.
I would like the swaggerUI to include the option to either select a file or post some json data. Can this be done?
and i read the documentation that the type property can be a array of types
"type": [null,"file"]
This is not valid in OpenAPI/Swagger. type must be a single type, and there's no null type.
I would like the swaggerUI to include the option to either select a file or post some json data.
In OpenAPI/Swagger 2.0 this is not possible – an operation can post either a file or JSON but not both. You'll need two operations - one that accepts JSON, and another one that accepts a file.
What you want will be possible using OpenAPI 3.0. However, I don't know if ASP.NET Core MVC supports OpenAPI 3.0; it may take some time before tools adopt the new version of OpenAPI.
Your API spec (in YAML) would look like this:
paths:
/something:
post:
requestBody:
description: Either a file or JSON object
required: true
content:
application/json:
schema:
type: object:
properties:
...
# Post a file via a multipart request
multipart/form-data:
schema:
type: object
properties:
file: # <-- here "file" is a form field name
type: string
format: binary
required:
- file
# or maybe...
# Post a file directly
application/octet-stream:
schema:
type: string
format: binary
responses:
...