Add support for documenting a portion of a request or response payload

Closes gh-312

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

@@ -0,0 +1,110 @@
+/*
+ * Copyright 2014-2016 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.restdocs.payload;
+
+import java.io.IOException;
+import java.util.List;
+import java.util.Map;
+
+import com.fasterxml.jackson.core.JsonParseException;
+import com.fasterxml.jackson.databind.JsonMappingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.ExpectedException;
+
+import org.springframework.http.MediaType;
+
+import static org.hamcrest.CoreMatchers.equalTo;
+import static org.hamcrest.CoreMatchers.is;
+import static org.junit.Assert.assertThat;
+
+/**
+ * Tests for {@link FieldPathPayloadSubsectionExtractor}.
+ *
+ * @author Andy Wilkinson
+ */
+public class FieldPathPayloadSubsectionExtractorTests {
+
+	@Rule
+	public final ExpectedException thrown = ExpectedException.none();
+
+	@Test
+	@SuppressWarnings("unchecked")
+	public void extractMapSubsectionOfJsonMap()
+			throws JsonParseException, JsonMappingException, IOException {
+		byte[] extractedPayload = new FieldPathPayloadSubsectionExtractor("a.b")
+				.extractSubsection("{\"a\":{\"b\":{\"c\":5}}}".getBytes(),
+						MediaType.APPLICATION_JSON);
+		Map<String, Object> extracted = new ObjectMapper().readValue(extractedPayload,
+				Map.class);
+		assertThat(extracted.size(), is(equalTo(1)));
+		assertThat(extracted.get("c"), is(equalTo((Object) 5)));
+	}
+
+	@Test
+	@SuppressWarnings("unchecked")
+	public void extractMultiElementArraySubsectionOfJsonMap()
+			throws JsonParseException, JsonMappingException, IOException {
+		byte[] extractedPayload = new FieldPathPayloadSubsectionExtractor("a")
+				.extractSubsection("{\"a\":[{\"b\":5},{\"b\":4}]}".getBytes(),
+						MediaType.APPLICATION_JSON);
+		List<Map<String, Object>> extracted = new ObjectMapper()
+				.readValue(extractedPayload, List.class);
+		assertThat(extracted.size(), is(equalTo(2)));
+		assertThat(extracted.get(0).get("b"), is(equalTo((Object) 5)));
+		assertThat(extracted.get(1).get("b"), is(equalTo((Object) 4)));
+	}
+
+	@Test
+	@SuppressWarnings("unchecked")
+	public void extractSingleElementArraySubsectionOfJsonMap()
+			throws JsonParseException, JsonMappingException, IOException {
+		byte[] extractedPayload = new FieldPathPayloadSubsectionExtractor("a.[]")
+				.extractSubsection("{\"a\":[{\"b\":5}]}".getBytes(),
+						MediaType.APPLICATION_JSON);
+		List<Map<String, Object>> extracted = new ObjectMapper()
+				.readValue(extractedPayload, List.class);
+		assertThat(extracted.size(), is(equalTo(1)));
+		assertThat(extracted.get(0).get("b"), is(equalTo((Object) 5)));
+	}
+
+	@Test
+	@SuppressWarnings("unchecked")
+	public void extractMapSubsectionFromSingleElementArrayInAJsonMap()
+			throws JsonParseException, JsonMappingException, IOException {
+		byte[] extractedPayload = new FieldPathPayloadSubsectionExtractor("a.[].b")
+				.extractSubsection("{\"a\":[{\"b\":{\"c\":5}}]}".getBytes(),
+						MediaType.APPLICATION_JSON);
+		Map<String, Object> extracted = new ObjectMapper().readValue(extractedPayload,
+				Map.class);
+		assertThat(extracted.size(), is(equalTo(1)));
+		assertThat(extracted.get("c"), is(equalTo((Object) 5)));
+	}
+
+	@Test
+	public void extractMapSubsectionFromMultiElementArrayInAJsonMap()
+			throws JsonParseException, JsonMappingException, IOException {
+		this.thrown.expect(PayloadHandlingException.class);
+		this.thrown.expectMessage(
+				equalTo("a.[].b does not uniquely identify a subsection of the payload"));
+		new FieldPathPayloadSubsectionExtractor("a.[].b").extractSubsection(
+				"{\"a\":[{\"b\":{\"c\":5}},{\"b\":{\"c\":6}}]}".getBytes(),
+				MediaType.APPLICATION_JSON);
+	}
+
+}

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

@@ -33,7 +33,9 @@ import org.springframework.restdocs.templates.mustache.MustacheTemplateEngine;
 import static org.hamcrest.CoreMatchers.containsString;
 import static org.mockito.BDDMockito.given;
 import static org.mockito.Mockito.mock;
+import static org.springframework.restdocs.payload.PayloadDocumentation.beneathPath;
 import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
+import static org.springframework.restdocs.payload.PayloadDocumentation.requestFields;
 import static org.springframework.restdocs.snippet.Attributes.attributes;
 import static org.springframework.restdocs.snippet.Attributes.key;
 
@@ -63,6 +65,19 @@ public class RequestFieldsSnippetTests extends AbstractSnippetTests {
 								.build());
 	}
 
+	@Test
+	public void subsectionOfMapRequest() throws IOException {
+		this.snippets.expect("request-fields-beneath-a")
+				.withContents(tableWithHeader("Path", "Type", "Description")
+						.row("`b`", "`Number`", "one").row("`c`", "`String`", "two"));
+
+		requestFields(beneathPath("a"), fieldWithPath("b").description("one"),
+				fieldWithPath("c").description("two"))
+						.document(this.operationBuilder.request("http://localhost")
+								.content("{\"a\": {\"b\": 5, \"c\": \"charlie\"}}")
+								.build());
+	}
+
 	@Test
 	public void arrayRequestWithFields() throws IOException {
 		this.snippets.expectRequestFields()
@@ -81,6 +96,19 @@ public class RequestFieldsSnippetTests extends AbstractSnippetTests {
 								.build());
 	}
 
+	@Test
+	public void subsectionOfArrayRequest() throws IOException {
+		this.snippets.expect("request-fields-beneath-[].a")
+				.withContents(tableWithHeader("Path", "Type", "Description")
+						.row("`b`", "`Number`", "one").row("`c`", "`String`", "two"));
+
+		requestFields(beneathPath("[].a"), fieldWithPath("b").description("one"),
+				fieldWithPath("c").description("two"))
+						.document(this.operationBuilder.request("http://localhost")
+								.content("[{\"a\": {\"b\": 5, \"c\": \"charlie\"}}]")
+								.build());
+	}
+
 	@Test
 	public void ignoredRequestField() throws IOException {
 		this.snippets.expectRequestFields()

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

@@ -26,6 +26,7 @@ import org.springframework.restdocs.AbstractSnippetTests;
 import org.springframework.restdocs.operation.Operation;
 import org.springframework.restdocs.templates.TemplateFormat;
 
+import static org.springframework.restdocs.payload.PayloadDocumentation.beneathPath;
 import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
 
 /**
@@ -60,6 +61,25 @@ public class RequestPartFieldsSnippetTests extends AbstractSnippetTests {
 														.build());
 	}
 
+	@Test
+	public void mapRequestPartSubsectionFields() throws IOException {
+		this.snippets.expect("request-part-one-fields-beneath-a")
+				.withContents(tableWithHeader("Path", "Type", "Description")
+						.row("`b`", "`Number`", "one").row("`c`", "`String`", "two"));
+
+		new RequestPartFieldsSnippet("one",
+				beneathPath("a"), Arrays
+						.asList(fieldWithPath("b").description("one"),
+								fieldWithPath("c").description("two")))
+										.document(
+												this.operationBuilder
+														.request("http://localhost")
+														.part("one",
+																"{\"a\": {\"b\": 5, \"c\": \"charlie\"}}"
+																		.getBytes())
+														.build());
+	}
+
 	@Test
 	public void multipleRequestParts() throws IOException {
 		this.snippets.expectRequestPartFields("one");

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

@@ -33,7 +33,9 @@ import org.springframework.restdocs.templates.mustache.MustacheTemplateEngine;
 import static org.hamcrest.CoreMatchers.containsString;
 import static org.mockito.BDDMockito.given;
 import static org.mockito.Mockito.mock;
+import static org.springframework.restdocs.payload.PayloadDocumentation.beneathPath;
 import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
+import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;
 import static org.springframework.restdocs.snippet.Attributes.attributes;
 import static org.springframework.restdocs.snippet.Attributes.key;
 
@@ -70,6 +72,18 @@ public class ResponseFieldsSnippetTests extends AbstractSnippetTests {
 								.build());
 	}
 
+	@Test
+	public void subsectionOfMapResponse() throws IOException {
+		this.snippets.expect("response-fields-beneath-a")
+				.withContents(tableWithHeader("Path", "Type", "Description")
+						.row("`b`", "`Number`", "one").row("`c`", "`String`", "two"));
+		responseFields(beneathPath("a"), fieldWithPath("b").description("one"),
+				fieldWithPath("c").description("two"))
+						.document(this.operationBuilder.response()
+								.content("{\"a\": {\"b\": 5, \"c\": \"charlie\"}}")
+								.build());
+	}
+
 	@Test
 	public void arrayResponseWithFields() throws IOException {
 		this.snippets.expectResponseFields()