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?

spring-projects-issues added the status: waiting-for-triageAn issue we've not yet triaged or decided on label

Nov 5, 2025

rstoyanchev requested changes

Nov 18, 2025

View reviewed changes

Copy link

Contributor

rstoyanchev left a comment•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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

Both Spring MVC and WebFlux listsupported return types. Neither of them mentionsResource 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 onResources underCodecs andMessage Converters. Then this can be mentioned as well as referenced from the list of return values forResponseEntity 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.

Copy link

Contributor

rstoyanchev commentedNov 18, 2025

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 haveMultipart Content for WebFlux and similar for WebMvc that cover uploads. Renaming that to Multipart Uploads, and creating another on Multipart Downloads would be fine.

rstoyanchev added type: documentation

A documentation task

in: web

Issues in web modules (web, webmvc, webflux, websocket)

status: waiting-for-feedbackWe need additional information before we can continue labels

Nov 18, 2025

Copy link

Author

verils commentedNov 18, 2025•
edited
Loading

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 returningResponseEntity<Flux<DataBuffer>> is the best option for me. Therefore, my main goal is to clarify it, theDataBuffer section is very close to the truth but isn't explicit enough.

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

I also usedResource for a while but encountered a side effect: theResourceHttpMessageWriter (in WebFlux) and theResourceHttpMessageConverter (in WebMvc) automatically override the response's Content-Type with media type from theResource. This can break anapplication/octet-stream download, and this behavior should also be documented.

spring-projects-issues added status: feedback-providedFeedback has been provided and removed status: waiting-for-feedbackWe need additional information before we can continue labels

Nov 18, 2025

Copy link

Contributor

rstoyanchev commentedNov 18, 2025

@verils, I don't think we should avoid documenting returningResource 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.