Swagger error with parameters in a multipart POST request - swagger

Question

I'm using Swagger Editor to document an existing API, built in Node, but it keeps giving me the following error:
Schema error at paths./upload/Rate.post.parameters[0]
is not exactly one from <#/definitions/parameter>,<#/definitions/jsonReference>
This error appears in 3 places of my code:
paths./upload/Rate.post.parameters[0]
paths./upload/Rate.post.parameters[1]
paths./users/register.post.parameters[0]
I've searched quite a bit, but, for example, this link did not solved my problem although it's the same error:
Swagger parameter error "is not exactly one from <#/definitions/parameter>"?
Here is my Swagger definition:
/users/register:
post:
tags:
- "users"
description: Allows an user to register at the Server
produces:
- application/json
parameters:
- name: body
in: body
description: JSON Object with information for a Register request from an User
schema:
type: object
required:
- username
- password
- weight
- height
- gender
- restRate
- age
properties:
username:
type: string
password:
type:
format: password
weight:
type: integer
height:
type: integer
gender:
type: string
restRate:
type: integer
age:
type: integer
# Expected responses for this operation:
responses:
# Response code
200:
description: Register successful
schema:
type: string
/upload/Rate:
post:
tags:
- "upload"
description: Allows an user to upload a file into the server
produces:
- application/json
consumes:
- multipart/form-data
parameters:
- name: body
in: formData
description: JSON Object with information for an upload request from an User
required: false
schema:
type: object
required:
- user
- overlap
- window
- latitude
- longitude
- time
- date
properties:
user:
type: string
overlap:
type: string
window:
type: string
latitude:
type: string
longitude:
type: string
time:
type: string
date:
type: string
- name: files
in: formData
description: File with the corresponding Rate
required: false
schema:
type: object
required:
- rate
properties:
rate:
type: file
# Expected responses for this operation:
responses:
# Response code
200:
description: Login successful
schema:
type: string
Maybe this will help, but the post route (upload/Rate) should receive a request that will be something like this, once I've parsed its parameters:
user = req.body.user;
rr = req.files.rate;
overlap = req.body.overlap;
windowT = req.body.window;
latitude = req.body.latitude;
longitude = req.body.longitude;
time = req.body.time;
date = req.body.date;
Thank you for your help and time!

Answer 1

There are multiple issues.
/upload/register:
Schema property password is missing the value for type.
Property name mismatch - restHR (under properties) vs restRate (in the required list).
upload/Rate:
The problem here is caused by object parameters in a multipart/form-data request. In OpenAPI (fka Swagger) 2.0, form parameters can be primitive values and arrays, but not objects. So your example cannot be described using OpenAPI 2.0.
If you were designing a new API (or if you could and were willing to change the API implementation to be compatible with OpenAPI 2.0), possible solutions would be:
Change the operation to consume application/json and combine all input parameters into a single JSON object. The file parameter would need to be implemented as a base64 string - type: string with format: byte.
Use multipart/form-data but split object parameters into individual form parameters.
The upcoming OpenAPI 3.0 will support object parameters in form data:
https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#special-considerations-for-multipart-content