Add example of sending back a file with RestResponse

Relates to: #50317

Co-authored-by: Stéphane Épardaud <[email protected]>

Author: geoand

docs/src/main/asciidoc/rest.adoc

@@ -778,6 +778,34 @@ public class Endpoint {
 NOTE: You can also use the Jakarta REST type link:{jaxrsapi}/jakarta/ws/rs/core/Response.html[`Response`] but it is
 not strongly typed to your entity.
 
+==== Responding with files
+
+When a file needs to be returned, the following code ensures that Quarkus properly streams the file contents to the client.
+
+[source,java]
+----
+package org.acme.rest;
+
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import org.jboss.resteasy.reactive.RestResponse;
+import org.jboss.resteasy.reactive.RestResponse.ResponseBuilder;
+
+@Path("")
+public class Endpoint {
+
+    @Path("file")
+    @GET
+    public RestResponse<java.nio.file.Path> largePathRestResponse() throws IOException {
+        java.nio.file.Path path = ...
+
+        return RestResponse.ResponseBuilder.ok(path)
+                .header(HttpHeaders.CONTENT_DISPOSITION, "some-file-name")
+                .build();
+    }
+}
+----
+
 ==== Using annotations
 
 Alternatively, if you only need to set the status code and / or HTTP headers with static values, you can use `@org.jboss.resteasy.reactive.ResponseStatus` and /or `ResponseHeader` respectively.