Openapi-specification: Support for multipart/mixed Content-Type

[grokify]

I have a use case to support the multipart/mixed content type as defined in RFC 2049. Use of this content type includes support for:

• multiple parts in sequence
• each part with its own content type and data
• each part separated by a boundary value included in the HTTP request Content-Type header

It seems like it would be ideal if Swagger could enable defining each part as a parameter with content type and, on submission, have Swagger UI create the MIME boundary, add the boundary to the HTTP request Content-Type header, and assemble the multipart parameters into a multi-part request body using the boundary.

It would be great to support this in Swagger natively.

[yonderblue]

:+1: for implementing this :)

[yonderblue]

Is there some way that a work around to at least allow a user to hand enter (or use the example to enter) the http body (including sub requests with their headers etc) and get them all back for multipart/mixed request/response?

[grokify]

As a workaround for a multipart/mixed request, I'm currently hardcoding a boundary value in the consumes MIME type and as example text in the body. It's not very flexible but it's straightforward and has been used by lots of people successfully so far. For example:

"consumes" : ["multipart/mixed; boundary=Boundary-----1234567890"],
"parameters" : {
     "in": "body",
     "default" : "--Boundary-----1234567890\n ... EXAMPLE HERE ... \n--Boundary-----1234567890--"
}

[yonderblue]

@grokify that's good to know thanks i'll try this out first thing tomorrow, how about the response though? So far I haven't been able to get it to show a response with multipart/mixed at all.

[yonderblue]

The above doesn't pass the validator, you have to add "schema": { "type": "string" } for that, and then the default field is at odds with the validator too, looks like a bug.

If only the default would work and a simple string example response I think most would be in business with at least a workaround.

[webron]

@gaillard - when you say 'allow the user to hand enter', do you mean via swagger-ui or in general?

[yonderblue]

Yes I mean in the UI. It would be great if the user could choose content type, body and headers of each multi part, but as a work around if we could let the user hand enter that like @grokify showed it would help tremendously. His way works unless you also want it to run through the validator, can that bug be fixed?

[webron]

@gaillard you have to add schema to the parameter. While I'd normally discourage the following definition, as a workaround you can try this:

"consumes" : ["multipart/mixed; boundary=Boundary-----1234567890"],
"parameters" : {
     "in": "body",
     "schema": { "type": "object" },
     "default" : "--Boundary-----1234567890\n ... EXAMPLE HERE ... \n--Boundary-----1234567890--"
}

[yonderblue]

That does not pass the validator though. I'm running the validator locally.

[webron]

What error do you get from the validator?

[yonderblue]

That the schema doesn't match. [{"level":"error","domain":"validation","keyword":"oneOf","message":"instance failed to match exactly one schema (matched 0 out of 2)","schema":{"loadingURI":"http://swagger.io/v2/schema.json#","pointer":"/definitions/parametersList/items"},"instance":{"pointer":"/paths/~1{version}~1batch/post/parameters/1"}}]

[yonderblue]

Also an example of the response does not work. Just like for this to be useful without full multipart/mixed support, we need a default to show the user in and out. It works with object schema type for the response but then shows in the example model like

{
  "multipart/mixed; boundary=test": "TODO the example"
}

which doesn't make any sense and why I was trying to use type string. So if the way it works with object could be there for string, it would be a decent workaround.

[webron]

@gaillard - let's take this to the google group as it's not directly related to the issue (this is just a workaround we're trying to employ, it won't change the issue at hand). There, just provide me with the definition of the POST /{version}/batch path, what you expect to see in the ui and what you actually experience.

[yonderblue]

Ok posted, thanks

[tleyden]

Feature request: multipart/related (merging https://github.com/swagger-api/swagger-spec/issues/520 into this)

[perotom]

Any updates on Content-Type and boundary?

[fehguy]

See #878