File upload support is currently partially/incorrectly documented

[mikebeaton]

Hi,

Would a PR adding (very brief) documentation for the file upload support be welcomed?

At the moment:

• The README.md still points the user to Swashbuckle.AspNetCore.Filters for file upload support, but in fact (on looking through the commit histories and issues of both projects - but unfortunately not the current README.md of either) file upload support has been in this project since 4.0, and hence has been removed from Swashbuckle.AspNetCore.Filters.

It would simplify tracking down how to use file uploads if that small piece of text in the README was removed.

• IFormFile is indeed now supported by this project, with a clean file upload button, but this does not work if the IFormFile is marked [FromForm], which is counterintuitive (to me, at least!)

With IformFile file parameter:

With [FromForm]IFormFile file parameter:

It would be helpful if the requirement not to tag IFormFile with [FromForm] was documented, since I guess (?!) that this is something that maybe not just I am going to try by mistake. (At the same time, having this info, very briefly, would serve the additional purpose of clarifying what the user has to do to get a file upload up and running, right in the README.)

Does that sound sensible? Thanks!

[domaindrivendev]

@mikebeaton makes sense. If you want to go ahead and create a PR for the docs update I'll be happy to merge. Thx

[dernop]

Is this really just a documentation issue and not a bug? I was stuck on this problem for two days now and i was only able to solve it by "trial-and-error", when i eventually removed the [FromForm] attribute from the IFormFile parameter.
Since the ASP app works fine WITH this attribute and i thus consider it "legal" to do, i rather consider this a bug. It should also work with this attribute...

[domaindrivendev]

@dernop - while it may not prevent your API from working, it's technically incorrect to decorate IFormFile parameters with the [FromForm] attribute. If you take a look at the official MS docs on file uploads you'll see there's absolutely no mention of the attribute.

While the type and the attribute sound related, they're actually expressing two different concepts. The IFormFile type indicates to the ASP.NET Core model binder that the parameter should be deserialized from binary data in the request payload. However, when you decorate it with the [FromForm] attribute, you're indicating that it's indidividual properties should be populated from corresponding form fields in the request payload.

This distinction is aptly captured in the ApiParameterDescription.Source property, which is part of the metadata that's surfaced by ASP.NET Core to Swashbuckle. For binary data, this property should have the value FormFile, whereas for form fields, it should have the value Form. When you decorate the parameter with the [FromForm] attribute, ASP.NET Core assigns the value Form which is semantically incorrect, causing downstream problems for libraries like Swashbuckle.

The fact that the API still behaves as you expect, even with the incorrect use of the attribute, is an issue you should take up with ASP.NET Core team. Swashbuckle depends heavily on the metadata that's surfaced from ASP.NET Core, and if that metadata states that the model is deserialized from form-fields as opposed to binary data, then that's how Swashbuckle will describe it.