Improve documentaton on controller return values for file downloads

[verils]

I've updated the documentation to indicate that a ResponseEntity can be returned from a WebFlux controller.

On a separate note, since file uploads and downloads are common requirements in the Spring framework, I believe it would be beneficial to create a dedicated page to guide developers through the process. I'd be happy to create one. What are your thoughts?

[rstoyanchev]

This is a worthwhile improvement to consider, but not how I would address it.

Both Spring MVC and WebFlux list supported return types. Neither of them mentions Resource explicitly, but that has more to do with the supported codecs (WebFlux) and message converters (WebMvc).

My suggestion is to begin by adding a subsection on Resources under Codecs and Message Converters. Then this can be mentioned as well as referenced from the list of return values for ResponseEntity and @ResponseBody.

Let me know if you plan to update the PR along those lines, or if you only update the WebFlux side, we can do the rest.

[rstoyanchev]

On a separate note, since file uploads and downloads are common requirements in the Spring framework, I believe it would be beneficial to create a dedicated page to guide developers through the process.

We have Multipart Content for WebFlux and similar for WebMvc that cover uploads. Renaming that to Multipart Uploads, and creating another on Multipart Downloads would be fine.

[verils]

Initially, the issue I encountered was that I didn't know how to handle content downloads in WebFlux, as there was no clear explanation in the documentation. I did some search online and finally found out that returning ResponseEntity<Flux<DataBuffer>> is the best option for me. Therefore, my main goal is to clarify it, the DataBuffer section is very close to the truth but isn't explicit enough.

As @rstoyanchev pointed out, the Return Values section is the best place to address this, I'm gonna add a Flux<DataBuffer> line to that table.

I also used Resource for a while but encountered a side effect: the ResourceHttpMessageWriter (in WebFlux) and the ResourceHttpMessageConverter (in WebMvc) automatically override the response's Content-Type with media type from the Resource. This can break an application/octet-stream download, and this behavior should also be documented.

[rstoyanchev]

@verils, I don't think we should avoid documenting returning Resource as a way to handle downloads just because of an issue you ran into. The issue should be considered to decide whether it is intentional, a limitation, something that needs fixing, and so on.

I will say briefly that if the returned ResponseEntity has the content-type set then I would expect it to get used. However, I would also want to know why the content type of the resource isn't the right one to begin with. This is best discussed in a separate issue.

[verils]

@rstoyanchev Yes, I agree that.

So I'll just deal with the return type list first.