Make it easier to document common portions of req and resp payloads

This commit adds a new andWithPrefix(String, FieldDescriptor[]) method
to both RequestFieldsSnippet and ResponseFieldsSnippet. It can be
used to add descriptors to an existing snippet, applying the given
prefix to the additional descriptors as it does so. This allows the
descriptors for a portion of a payload to be created once and then
reused, irrespective of where in the payload the portion appears.

Closes gh-221

spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/AbstractFieldsSnippet.java

@@ -180,4 +180,30 @@ public abstract class AbstractFieldsSnippet extends TemplatedSnippet {
 		return model;
 	}
 
+	/**
+	 * Creates a copy of the given {@code descriptors} with the given {@code pathPrefix}
+	 * applied to their paths.
+	 *
+	 * @param pathPrefix the path prefix
+	 * @param descriptors the descriptors to copy
+	 * @return the copied descriptors with the prefix applied
+	 */
+	protected final List<FieldDescriptor> applyPathPrefix(String pathPrefix,
+			List<FieldDescriptor> descriptors) {
+		List<FieldDescriptor> prefixedDescriptors = new ArrayList<>();
+		for (FieldDescriptor descriptor : descriptors) {
+			FieldDescriptor prefixedDescriptor = new FieldDescriptor(
+					pathPrefix + descriptor.getPath())
+							.description(descriptor.getDescription())
+							.type(descriptor.getType());
+			if (descriptor.isIgnored()) {
+				prefixedDescriptor.ignored();
+			}
+			if (descriptor.isOptional()) {
+				prefixedDescriptor.optional();
+			}
+			prefixedDescriptors.add(prefixedDescriptor);
+		}
+		return prefixedDescriptors;
+	}
 }

spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/RequestFieldsSnippet.java

@@ -72,13 +72,30 @@ public class RequestFieldsSnippet extends AbstractFieldsSnippet {
 	 * Returns a new {@code RequestFieldsSnippet} configured with this snippet's
 	 * attributes and its descriptors combined with the given
 	 * {@code additionalDescriptors}.
+	 *
 	 * @param additionalDescriptors the additional descriptors
 	 * @return the new snippet
 	 */
 	public RequestFieldsSnippet and(FieldDescriptor... additionalDescriptors) {
+		return andWithPrefix("", additionalDescriptors);
+	}
+
+	/**
+	 * Returns a new {@code RequestFieldsSnippet} configured with this snippet's
+	 * attributes and its descriptors combined with the given
+	 * {@code additionalDescriptors}. The given {@code pathPrefix} is applied to the path
+	 * of each additional descriptor.
+	 *
+	 * @param pathPrefix the prefix to apply to the additional descriptors
+	 * @param additionalDescriptors the additional descriptors
+	 * @return the new snippet
+	 */
+	public RequestFieldsSnippet andWithPrefix(String pathPrefix,
+			FieldDescriptor... additionalDescriptors) {
 		List<FieldDescriptor> combinedDescriptors = new ArrayList<>();
 		combinedDescriptors.addAll(getFieldDescriptors());
-		combinedDescriptors.addAll(Arrays.asList(additionalDescriptors));
+		combinedDescriptors.addAll(
+				applyPathPrefix(pathPrefix, Arrays.asList(additionalDescriptors)));
 		return new RequestFieldsSnippet(combinedDescriptors, this.getAttributes());
 	}
 

spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/ResponseFieldsSnippet.java

@@ -72,13 +72,30 @@ public class ResponseFieldsSnippet extends AbstractFieldsSnippet {
 	 * Returns a new {@code ResponseFieldsSnippet} configured with this snippet's
 	 * attributes and its descriptors combined with the given
 	 * {@code additionalDescriptors}.
+	 *
 	 * @param additionalDescriptors the additional descriptors
 	 * @return the new snippet
 	 */
 	public ResponseFieldsSnippet and(FieldDescriptor... additionalDescriptors) {
+		return andWithPrefix("", additionalDescriptors);
+	}
+
+	/**
+	 * Returns a new {@code ResponseFieldsSnippet} configured with this snippet's
+	 * attributes and its descriptors combined with the given
+	 * {@code additionalDescriptors}. The given {@code pathPrefix} is applied to the path
+	 * of each additional descriptor.
+	 *
+	 * @param pathPrefix the prefix to apply to the additional descriptors
+	 * @param additionalDescriptors the additional descriptors
+	 * @return the new snippet
+	 */
+	public ResponseFieldsSnippet andWithPrefix(String pathPrefix,
+			FieldDescriptor... additionalDescriptors) {
 		List<FieldDescriptor> combinedDescriptors = new ArrayList<>();
 		combinedDescriptors.addAll(getFieldDescriptors());
-		combinedDescriptors.addAll(Arrays.asList(additionalDescriptors));
+		combinedDescriptors.addAll(
+				applyPathPrefix(pathPrefix, Arrays.asList(additionalDescriptors)));
 		return new ResponseFieldsSnippet(combinedDescriptors, this.getAttributes());
 	}
 

spring-restdocs-core/src/test/java/org/springframework/restdocs/payload/RequestFieldsSnippetTests.java

@@ -176,4 +176,19 @@ public class RequestFieldsSnippetTests extends AbstractSnippetTests {
 						.content("{\"a\": {\"b\": 5, \"c\": \"charlie\"}}").build());
 	}
 
+	@Test
+	public void prefixedAdditionalDescriptors() throws IOException {
+		this.snippet.expectRequestFields("prefixed-additional-descriptors")
+				.withContents(tableWithHeader("Path", "Type", "Description")
+						.row("a", "Object", "one").row("a.b", "Number", "two")
+						.row("a.c", "String", "three"));
+
+		PayloadDocumentation.requestFields(fieldWithPath("a").description("one"))
+				.andWithPrefix("a.", fieldWithPath("b").description("two"),
+						fieldWithPath("c").description("three"))
+				.document(operationBuilder("prefixed-additional-descriptors")
+						.request("http://localhost")
+						.content("{\"a\": {\"b\": 5, \"c\": \"charlie\"}}").build());
+	}
+
 }

spring-restdocs-core/src/test/java/org/springframework/restdocs/payload/ResponseFieldsSnippetTests.java

@@ -232,4 +232,18 @@ public class ResponseFieldsSnippetTests extends AbstractSnippetTests {
 						.build());
 	}
 
+	@Test
+	public void prefixedAdditionalDescriptors() throws IOException {
+		this.snippet.expectResponseFields("prefixed-additional-descriptors")
+				.withContents(tableWithHeader("Path", "Type", "Description")
+						.row("a", "Object", "one").row("a.b", "Number", "two")
+						.row("a.c", "String", "three"));
+
+		PayloadDocumentation.responseFields(fieldWithPath("a").description("one"))
+				.andWithPrefix("a.", fieldWithPath("b").description("two"),
+						fieldWithPath("c").description("three"))
+				.document(operationBuilder("prefixed-additional-descriptors").response()
+						.content("{\"a\": {\"b\": 5, \"c\": \"charlie\"}}").build());
+	}
+
 }