7

I'm writing API documentation using Swagger Editor, but having a problem with a multipart POST request containing a JSON object. Here is my Swagger YAML file:

swagger: '2.0' info: version: 1.0.0 title: Documentation API paths: /agent: post: consumes: - multipart/form-data produces: - text/html parameters: - in: query name: method description: name of method to access required: true type: string - in: body name: param description: parameter to send required: true schema: $ref: "#/definitions/Param" responses: 201: description: item created 400: description: invalid input, object invalid 409: description: an existing item already exists definitions: Param: # <---------- type: object required: - username - password - imsi - imei - deviceId properties: username: type: string password: type: string imsi: type: string imei: type: string deviceId: type: string host: 'localhost' basePath: /v1/api schemes: - https

When I execute the request, I get the curl command like this:

curl -X POST "https://localhost/v1/api/agent?method=login" -H "accept: text/html" -H "content-type: multipart/form-data" -F {"username":"1234567890","password":"1234567890","imsi":"310260000000000","imei":"000000000000000","deviceId":"9ca9b02b237a6dae"}

but I expect to get this:

curl -X POST "https://localhost/v1/api/agent?method=login" -H "accept: text/html" -H "content-type: multipart/form-data" -F 'param={"username":"1234567890","password":"1234567890","imsi":"310260000000000","imei":"000000000000000","deviceId":"9ca9b02b237a6dae"}'

That is, the body parameter should be sent with the key name param.

Improve this question

1 Answer 1

Reset to default
12

multipart/* requests containing JSON objects can be described using OpenAPI 3.0 but not OpenAPI/Swagger 2.0.

OpenAPI 3.0

OpenAPI 3.0 natively supports JSON objects in multipart/form-data requests:

paths: /agent: post: parameters: - in: query name: method description: name of method to access required: true schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object properties: # Here, "param" is part/parameter name in a multipart payload. # Parameter value is an object defined by the "Param" schema. # Default Content-Type for objects is application/json. param: $ref: "#/components/schemas/Param" responses: ...

OpenAPI 2.0

In OpenAPI/Swagger 2.0, when consuming form data (application/x-www-form-urlencoded or multipart/form-data), form parameters whose value is a JSON string are described as just type: string, and you cannot define the structure of the JSON string.

paths: /agent: post: consumes: - multipart/form-data produces: - text/html parameters: - ... - in: formData # <------- name: param description: parameter to send required: true type: string # <-------

To pass in a JSON object, the operation needs to consume application/json instead:

paths: /agent: post: consumes: - application/json # <----- produces: - text/html parameters: - ... - in: body name: param description: parameter to send required: true schema: $ref: "#/definitions/Param"
Improve this answer
Sign up to request clarification or add additional context in comments.

1 Comment

+1, and more examples of requestBody are around now that 3.0 is out.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.