Allow model types to be of type=file

[Danielku15]

Currently only operation parameters can be of type file but in some scenarios you want to have the file as part of your model. In our API we have 1 input model defined for our operation:

"FileUploadRequestViewModel": {
    "required": ["username", "file"],
    "type": "object",
    "properties": {
        "username": {
            "description": "The username of the file owner.",
            "type": "string"
        },
        "description": {
            "description": "A description of the file contents",
            "type": "string"
        },
        "file": {
            "description": "The file to upload.",
            "type": "file"
        }
    }
},

If any model property is of type file, the operation must be called with multipart/form-data. An operation could look like this:

"/v1/files": {
    "post": {
        "summary": "Uploads a new file to the data repository.",
        "operationId": "Files_Upload",
        "consumes": ["multipart/form-data"],
        "produces": ["application/json", "text/json"],
        "parameters": [{
            "name": "request",
            "in": "body",
            "description": "The model describing the file to be uploaded",
            "required": true,
            "schema": {
                "$ref": "#/definitions/FileUploadRequestViewModel"
            }
        }],
        "responses": {
            "200": {
                "description": "The file already existed in the repository and was updated.",
                "schema": {
                    "$ref": "#/definitions/FileUploadResponseViewModel"
                }
            },
            "201": {
                "description": "The file push was successful and it was added as new to the file repository.",
                "schema": {
                    "$ref": "#/definitions/FileUploadResponseViewModel"
                }
            },
            "404": {
                "description": "No user with the given username could be found."
            },
            "415": {
                "description": "If the file push was not called with a multipart mimetype"
            },
            "400": {
                "description": "One or more of the input parameters were invalid, check the body for detailed validation messages.",
                "schema": {
                    "$ref": "#/definitions/HttpError"
                }
            }
        },
        "deprecated": false
    }
},

In the example above, the user would send the following content to upload a file:

POST /v1/files HTTP/1.1
{{Other Headers}}
Content-Type: multipart/form-data; boundary=--389C9546-8F63-47C8-A1D7-51B7D88FDB08
Content-Length: {{Actual Length}}

--389C9546-8F63-47C8-A1D7-51B7D88FDB08
Content-Disposition: form-data; name="request.username"

Username
--389C9546-8F63-47C8-A1D7-51B7D88FDB08
Content-Disposition: form-data; name="request.description"

An archive of my holiday pictures.
-----------------------------735323031399963166993862150
Content-Disposition: form-data; name="request.file"; filename="MyHolidayPictures.zip"
Content-Type: application/zip

{{Binary Content}}
--389C9546-8F63-47C8-A1D7-51B7D88FDB08--

As you can see the model properties are accessed via the name of the single multipart boundaries.

[ePaul]

I think currently (with OpenAPI 2.0) you would simply define several form parameters, one of which would be the file type one. Does this not work for you?

[Danielku15]

Yes, with the OpenAPI 2.0 this would work with flattening the model or pulling out the file parameters to the operation contract. But with this you loose all benefits that you have with models like:

• You can reuse them across multiple operations and models.
• You can have arrays of your model supporting multiple file uploads.

Looking at the API from implementation perspective, it totally makes sense (to me) to have the file upload as part of the data model where you store the related information to the file.

[webron]

Thanks. You've given a good idea on how to deal with an existing issue (or a set of issues) and I'll consider that when approaching it. Need to process it some more, but it may be a way to eliminate formData parameters and provide the extra flexibility that's missing now. No guarantees though.

[webron]

Partially tackling PR: #741

[fehguy]

File is dead! Long live File.

See #878