Swagger error with parameters in a multipart POST request

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