Openapi-specification: Allow different Content Types in File type parameters

[thorntech]

For multipart uploads that contain a file and some other part, like a JSON object, it would be very useful to be able to specify a content type on the File parts other than the actual binary file. This is critical for Java applications that need the content type of the part in order to know how to deserialize the json or xml into a Java object.

For what its worth, I was able to get this working by modifying swagger-ui,js to use a Blob as the FormData. I had to add a "contentType" field to the Parameter object. I know this violates the spec, but this worked for my project.

swagger-ui.js line 1797:

if (param.paramType === 'form') {
      if (param.type.toLowerCase() !== 'file' && map[param.name] !== void 0) {
        if(typeof param.contentType !== 'undefined') {
            bodyParam.append(param.name, new Blob([map[param.name]], { type: param.contentType}));
        }
        else {
            bodyParam.append(param.name, map[param.name]);
        }
      }
    }

In the swagger doc, I can define the file and the json object parameters like so:

        {
         "name": "story",
         "description": "The story object in json format",
         "required": true,
         "paramType": "form",
         "type": "Story",
         "contentType": "application/json"
        },
        {
         "name": "file",
         "description": "The base64 encoded multipart file attachment. ",            
         "required": true,
         "paramType": "form",
         "type": "File"
        }

Refer to this discussion / issue in swagger-core for more detail - https://github.com/swagger-api/swagger-core/issues/636

[webron]

I'll just add and say that for now vendor extensions can be used to extend this functionality, but we should consider it for the next version.

_Technically_, the format field could be used for it as well in 2.0, but that's more hackish and I don't think we should officially support it.

[christopheblin]

I'll just add and say that for now vendor extensions can be used to extend this functionality

Could you elaborate on this please.
I'm having the same problem but I have no clue what you mean with this sentence...

[webron]

@christopheblin - of course. If you take the file definition from above as an example:

        {
         "name": "file",
         "description": "The base64 encoded multipart file attachment. ",            
         "required": true,
         "paramType": "form",
         "type": "file",
         "x-mimetype": "image/jpeg"
        }

This could indicate that the specific file parameter needs to be of an image/jpeg mime type.

[webron]

Parent: #565

[jmdacruz]

This is a very common pattern on REST APIs when you have to upload some binary content and its related metadata in JSON. In those cases, it is desirable to be able to define:

• The Content-Type for the overall request, which could be anything on the multipart family (e.g., multipart/related, multipart/mixed, multipart/alternative). The distinction in this family of types is important, since content is not handled in the same way depending on the subtype, and you must be able to use Content Negotiation later on to retrieve each of the portions of the request.
• The Content-Type for each individual part of the payload, e.g., application/json for the JSON object which is represented with a JSON schema in Swagger, application/octet-stream for a binary file, application/javascript for a JavaScript file, etc.

[webron]

You can do that now!