Update reference with examples of multipart requests

Issue: SPR-16118

Author: rstoyanchev

spring-test/src/main/java/org/springframework/test/web/reactive/server/WebTestClient.java

@@ -615,6 +615,17 @@ interface RequestBodySpec extends RequestHeadersSpec<RequestBodySpec> {
 		/**
 		 * Set the body of the request to the given synchronous {@code Object} and
 		 * perform the request.
+		 * <p>This method is a convenient shortcut for:
+		 * <pre class="code">
+		 * .body(BodyInserters.fromObject(object))
+		 * </pre>
+		 * <p>The body can be a
+		 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create
+		 * a multipart request. The values in the {@code MultiValueMap} can be
+		 * any Object representing the body of the part, or an
+		 * {@link org.springframework.http.HttpEntity HttpEntity} representing a
+		 * part with body and headers. The {@code MultiValueMap} can be built
+		 * conveniently using
 		 * @param body the {@code Object} to write to the request
 		 * @return a {@code Mono} with the response
 		 */

spring-web/src/main/java/org/springframework/web/client/RestOperations.java

@@ -149,9 +149,13 @@ <T> ResponseEntity<T> getForEntity(String url, Class<T> responseType, Map<String
 	 * the {@code Location} header. This header typically indicates where the new resource is stored.
 	 * <p>URI Template variables are expanded using the given URI variables, if any.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
-	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
-	 * simulate a multipart from submission.
+	 * add additional HTTP headers to the request.
+	 * <p>The body of the entity, or {@code request} itself, can be a
+	 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request.
+	 * The values in the {@code MultiValueMap} can be any Object representing the body of the part,
+	 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body
+	 * and headers. The {@code MultiValueMap} can be built conveniently using
+	 * {@link org.springframework.http.client.MultipartBodyBuilder MultipartBodyBuilder}.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
@@ -166,9 +170,13 @@ <T> ResponseEntity<T> getForEntity(String url, Class<T> responseType, Map<String
 	 * the {@code Location} header. This header typically indicates where the new resource is stored.
 	 * <p>URI Template variables are expanded using the given map.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
-	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
-	 * simulate a multipart from submission.
+	 * add additional HTTP headers to the request
+	 * <p>The body of the entity, or {@code request} itself, can be a
+	 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request.
+	 * The values in the {@code MultiValueMap} can be any Object representing the body of the part,
+	 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body
+	 * and headers. The {@code MultiValueMap} can be built conveniently using
+	 * {@link org.springframework.http.client.MultipartBodyBuilder MultipartBodyBuilder}.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
@@ -183,9 +191,13 @@ URI postForLocation(String url, @Nullable Object request, Map<String, ?> uriVari
 	 * Create a new resource by POSTing the given object to the URL, and returns the value of the
 	 * {@code Location} header. This header typically indicates where the new resource is stored.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
- 	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
- 	 * simulate a multipart from submission.
+	 * add additional HTTP headers to the request.
+	 * <p>The body of the entity, or {@code request} itself, can be a
+	 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request.
+	 * The values in the {@code MultiValueMap} can be any Object representing the body of the part,
+	 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body
+	 * and headers. The {@code MultiValueMap} can be built conveniently using
+	 * {@link org.springframework.http.client.MultipartBodyBuilder MultipartBodyBuilder}.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @return the value for the {@code Location} header
@@ -199,9 +211,13 @@ URI postForLocation(String url, @Nullable Object request, Map<String, ?> uriVari
 	 * and returns the representation found in the response.
 	 * <p>URI Template variables are expanded using the given URI variables, if any.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
- 	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
- 	 * simulate a multipart from submission.
+	 * add additional HTTP headers to the request.
+	 * <p>The body of the entity, or {@code request} itself, can be a
+	 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request.
+	 * The values in the {@code MultiValueMap} can be any Object representing the body of the part,
+	 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body
+	 * and headers. The {@code MultiValueMap} can be built conveniently using
+	 * {@link org.springframework.http.client.MultipartBodyBuilder MultipartBodyBuilder}.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param responseType the type of the return value
@@ -218,9 +234,13 @@ <T> T postForObject(String url, @Nullable Object request, Class<T> responseType,
 	 * and returns the representation found in the response.
 	 * <p>URI Template variables are expanded using the given map.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
-	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
- 	 * simulate a multipart from submission.
+	 * add additional HTTP headers to the request.
+	 * <p>The body of the entity, or {@code request} itself, can be a
+	 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request.
+	 * The values in the {@code MultiValueMap} can be any Object representing the body of the part,
+	 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body
+	 * and headers. The {@code MultiValueMap} can be built conveniently using
+	 * {@link org.springframework.http.client.MultipartBodyBuilder MultipartBodyBuilder}.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param responseType the type of the return value
@@ -236,9 +256,13 @@ <T> T postForObject(String url, @Nullable Object request, Class<T> responseType,
 	 * Create a new resource by POSTing the given object to the URL,
 	 * and returns the representation found in the response.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
- 	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
- 	 * simulate a multipart from submission.
+	 * add additional HTTP headers to the request.
+	 * <p>The body of the entity, or {@code request} itself, can be a
+	 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request.
+	 * The values in the {@code MultiValueMap} can be any Object representing the body of the part,
+	 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body
+	 * and headers. The {@code MultiValueMap} can be built conveniently using
+	 * {@link org.springframework.http.client.MultipartBodyBuilder MultipartBodyBuilder}.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param responseType the type of the return value
@@ -253,9 +277,13 @@ <T> T postForObject(String url, @Nullable Object request, Class<T> responseType,
 	 * and returns the response as {@link ResponseEntity}.
 	 * <p>URI Template variables are expanded using the given URI variables, if any.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
-	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
-	 * simulate a multipart from submission.
+	 * add additional HTTP headers to the request.
+	 * <p>The body of the entity, or {@code request} itself, can be a
+	 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request.
+	 * The values in the {@code MultiValueMap} can be any Object representing the body of the part,
+	 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body
+	 * and headers. The {@code MultiValueMap} can be built conveniently using
+	 * {@link org.springframework.http.client.MultipartBodyBuilder MultipartBodyBuilder}.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
@@ -271,9 +299,13 @@ <T> ResponseEntity<T> postForEntity(String url, @Nullable Object request, Class<
 	 * and returns the response as {@link HttpEntity}.
 	 * <p>URI Template variables are expanded using the given map.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
- 	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
- 	 * simulate a multipart from submission.
+	 * add additional HTTP headers to the request.
+	 * <p>The body of the entity, or {@code request} itself, can be a
+	 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request.
+	 * The values in the {@code MultiValueMap} can be any Object representing the body of the part,
+	 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body
+	 * and headers. The {@code MultiValueMap} can be built conveniently using
+	 * {@link org.springframework.http.client.MultipartBodyBuilder MultipartBodyBuilder}.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
@@ -288,9 +320,13 @@ <T> ResponseEntity<T> postForEntity(String url, @Nullable Object request, Class<
 	 * Create a new resource by POSTing the given object to the URL,
 	 * and returns the response as {@link ResponseEntity}.
 	 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to
-	 * add additional HTTP headers to the request. The body of the entity, or {@code request} itself,
- 	 * can be a {@link org.springframework.http.client.MultipartBodyBuilder MultiValueMap} to
- 	 * simulate a multipart from submission.
+	 * add additional HTTP headers to the request.
+	 * <p>The body of the entity, or {@code request} itself, can be a
+	 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request.
+	 * The values in the {@code MultiValueMap} can be any Object representing the body of the part,
+	 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body
+	 * and headers. The {@code MultiValueMap} can be built conveniently using
+	 * {@link org.springframework.http.client.MultipartBodyBuilder MultipartBodyBuilder}.
 	 * @param url the URL
 	 * @param request the Object to be POSTed (may be {@code null})
 	 * @return the converted object

spring-webflux/src/main/java/org/springframework/web/reactive/function/BodyInserters.java

@@ -220,10 +220,13 @@ public static FormInserter<String> fromFormData(String key, String value) {
 
 	/**
 	 * Return a {@code FormInserter} that writes the given {@code MultiValueMap}
-	 * as multipart data. The {@code multipartData} parameter can conveniently be built using the
-	 * {@link org.springframework.http.client.MultipartBodyBuilder MultipartBodyBuilder}.
-	 * Note that the returned inserter allows for additional entries to be added
-	 * via {@link FormInserter#with(String, Object)}.
+	 * as multipart data. The values in the {@code MultiValueMap} can be any
+	 * Object representing the body of the part, or an
+	 * {@link org.springframework.http.HttpEntity HttpEntity} representing a part
+	 * with body and headers. The {@code MultiValueMap} can be built conveniently
+	 * using {@link org.springframework.http.client.MultipartBodyBuilder
+	 * MultipartBodyBuilder}. Also the returned inserter allows for additional
+	 * entries to be added via {@link FormInserter#with(String, Object)}.
 	 *
 	 * <p><strong>Note:</strong> you can also use the {@code syncBody(Object)}
 	 * method in the request builders of both the {@code WebClient} and
@@ -245,15 +248,13 @@ public static <T> FormInserter<T> fromMultipartData(MultiValueMap<String, T> mul
 	}
 
 	/**
-	 * Return a {@code FormInserter} that writes the key-value pair  as multipart data. The
-	 * {@code multipartData} parameter can conveniently be built using the
-	 * {@link org.springframework.http.client.MultipartBodyBuilder MultipartBodyBuilder}.
-	 * Note that the returned inserter allows for additional entries to be added
-	 * via {@link FormInserter#with(String, Object)}.
-	 * {@link FormInserter#with(String, Object)}.
-	 * @param key the key to add to the form
-	 * @param value the value to add to the form
-	 * @return a {@code FormInserter} that writes multipart data
+	 * A variant of {@link #fromMultipartData(MultiValueMap)} for adding
+	 * parts as name-value pairs in-line vs building a {@code MultiValueMap}
+	 * and passing it in.
+	 * @param key the part name
+	 * @param value the part value, an Object or {@code HttpEntity}
+	 * @return a {@code FormInserter} that can writes the provided multipart
+	 * data and also allows adding more parts
 	 */
 	// Note that the returned BodyInserter is parameterized to ClientHttpRequest, not
 	// ReactiveHttpOutputMessage like other methods, since sending form data only typically happens

spring-webflux/src/main/java/org/springframework/web/reactive/function/client/WebClient.java

@@ -544,9 +544,17 @@ interface RequestBodySpec extends RequestHeadersSpec<RequestBodySpec> {
 
 		/**
 		 * Set the body of the request to the given synchronous {@code Object}.
-		 * <p>This method is a convenient shortcut for {@link #body(BodyInserter)} with a
-		 * {@linkplain org.springframework.web.reactive.function.BodyInserters#fromObject
-		 * Object body inserter}.
+		 * <p>This method is a convenient shortcut for:
+		 * <pre class="code">
+		 * .body(BodyInserters.fromObject(object))
+		 * </pre>
+		 * <p>The body can be a
+		 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create
+		 * a multipart request. The values in the {@code MultiValueMap} can be
+		 * any Object representing the body of the part, or an
+		 * {@link org.springframework.http.HttpEntity HttpEntity} representing a
+		 * part with body and headers. The {@code MultiValueMap} can be built
+		 * conveniently using
 		 * @param body the {@code Object} to write to the request
 		 * @return this builder
 		 */

spring-webflux/src/test/java/org/springframework/web/reactive/function/MultipartIntegrationTests.java

@@ -23,10 +23,12 @@
 import reactor.test.StepVerifier;
 
 import org.springframework.core.io.ClassPathResource;
+import org.springframework.core.io.Resource;
 import org.springframework.http.HttpEntity;
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
+import org.springframework.http.client.MultipartBodyBuilder;
 import org.springframework.http.codec.multipart.FilePart;
 import org.springframework.http.codec.multipart.FormFieldPart;
 import org.springframework.http.codec.multipart.Part;
@@ -75,16 +77,11 @@ public void parts() {
 				.verifyComplete();
 	}
 
-	private MultiValueMap<String, Object> generateBody() {
-		HttpHeaders fooHeaders = new HttpHeaders();
-		fooHeaders.setContentType(MediaType.TEXT_PLAIN);
-		ClassPathResource fooResource = new ClassPathResource("org/springframework/http/codec/multipart/foo.txt");
-		HttpEntity<ClassPathResource> fooPart = new HttpEntity<>(fooResource, fooHeaders);
-		HttpEntity<String> barPart = new HttpEntity<>("bar");
-		MultiValueMap<String, Object> parts = new LinkedMultiValueMap<>();
-		parts.add("fooPart", fooPart);
-		parts.add("barPart", barPart);
-		return parts;
+	private MultiValueMap<String, HttpEntity<?>> generateBody() {
+		MultipartBodyBuilder builder = new MultipartBodyBuilder();
+		builder.part("fooPart", new ClassPathResource("org/springframework/http/codec/multipart/foo.txt"));
+		builder.part("barPart", "bar");
+		return builder.build();
 	}
 
 	@Override

spring-webflux/src/test/java/org/springframework/web/reactive/result/method/annotation/MultipartIntegrationTests.java

@@ -32,16 +32,14 @@
 import org.springframework.context.annotation.Configuration;
 import org.springframework.core.io.ClassPathResource;
 import org.springframework.http.HttpEntity;
-import org.springframework.http.HttpHeaders;
 import org.springframework.http.HttpStatus;
-import org.springframework.http.MediaType;
+import org.springframework.http.client.MultipartBodyBuilder;
 import org.springframework.http.codec.multipart.FilePart;
 import org.springframework.http.codec.multipart.FormFieldPart;
 import org.springframework.http.codec.multipart.MultipartHttpMessageReader;
 import org.springframework.http.codec.multipart.Part;
 import org.springframework.http.server.reactive.AbstractHttpHandlerIntegrationTests;
 import org.springframework.http.server.reactive.HttpHandler;
-import org.springframework.util.LinkedMultiValueMap;
 import org.springframework.util.MultiValueMap;
 import org.springframework.web.bind.annotation.ModelAttribute;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -136,27 +134,13 @@ public void modelAttribute() {
 				.verifyComplete();
 	}
 
-
-	private MultiValueMap<String, Object> generateBody() {
-
-		MultiValueMap<String, Object> parts = new LinkedMultiValueMap<>();
-		parts.add("fieldPart", "fieldValue");
-
-		HttpHeaders headers = new HttpHeaders();
-		headers.setContentType(MediaType.TEXT_PLAIN);
-		ClassPathResource resource = new ClassPathResource("foo.txt", MultipartHttpMessageReader.class);
-		parts.add("fileParts", new HttpEntity<>(resource, headers));
-
-		headers = new HttpHeaders();
-		headers.setContentType(MediaType.IMAGE_PNG);
-		resource = new ClassPathResource("logo.png", getClass());
-		parts.add("fileParts", new HttpEntity<>(resource, headers));
-
-		headers = new HttpHeaders();
-		headers.setContentType(MediaType.APPLICATION_JSON);
-		parts.add("jsonPart", new HttpEntity<>(new Person("Jason"), headers));
-
-		return parts;
+	private MultiValueMap<String, HttpEntity<?>> generateBody() {
+		MultipartBodyBuilder builder = new MultipartBodyBuilder();
+		builder.part("fieldPart", "fieldValue");
+		builder.part("fileParts", new ClassPathResource("foo.txt", MultipartHttpMessageReader.class));
+		builder.part("fileParts", new ClassPathResource("logo.png", getClass()));
+		builder.part("jsonPart", new Person("Jason"));
+		return builder.build();
 	}
 
 

src/docs/asciidoc/testing-webtestclient.adoc

@@ -293,3 +293,13 @@ from the `reactor-test` module to do that, for example:
             .thenCancel()
             .verify();
 ----
+
+
+[[webtestclient-request-body]]
+=== Request body
+
+When it comes to building requests, the `WebTestClient` offers an identical API as the
+`WebClient` and the implementation is mostly a simple pass-through. Please refer
+to the <<web-reactive.adoc#webflux-client-body,WebClient documentation>> for examples on
+how to prepare a request with a body including submitting form data, multipart requests,
+and more.