Allow an item to be undocumented without it causing a test failure

Previously, it was necessary to document every payload field, link,
path parameter, or request. If an item was not documented a failure
would occur. This has proven to be too restrictive for some use cases,
for example splitting up the documentation of a payload’s fields. While
it was possible to use a preprocessor to modify the operation prior to
documentation to remove the items that should not be documented, this
was more difficult than it needed to be.

This commit adds support for marking a descriptor as ignored. Ignored
descriptors count when checking that everything has been documented but
do not actually appear in the generated documentation.

Closes gh-143

spring-restdocs-mockmvc/src/test/java/org/springframework/restdocs/mockmvc/MockMvcRestDocumentationIntegrationTests.java

@@ -400,6 +400,30 @@ public class MockMvcRestDocumentationIntegrationTests {
 												"$ curl 'http://localhost:8080/custom/' -i -H 'Accept: application/json'"))));
 	}
 
+	@Test
+	public void stackOverflowQuestion() throws Exception {
+		MockMvc mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
+				.apply(documentationConfiguration(this.restDocumentation)).build();
+
+		mockMvc.perform(get("/company/5").accept(MediaType.APPLICATION_JSON))
+				.andExpect(status().isOk())
+				.andDo(document(
+						"company",
+						responseFields(
+								fieldWithPath("companyName").description(
+										"The name of the company"),
+								fieldWithPath("employee").description(
+										"An array of the company's employees"))))
+				.andDo(document(
+						"employee",
+						responseFields(
+								fieldWithPath("companyName").ignored(),
+								fieldWithPath("employee[].name").description(
+										"The name of the employee"),
+								fieldWithPath("employee[].age").description(
+										"The age of the employee"))));
+	}
+
 	private void assertExpectedSnippetFilesExist(File directory, String... snippets) {
 		for (String snippet : snippets) {
 			assertTrue(new File(directory, snippet).isFile());
@@ -434,6 +458,11 @@ public class MockMvcRestDocumentationIntegrationTests {
 					HttpStatus.OK);
 		}
 
+		@RequestMapping(value = "/company/5", produces = MediaType.APPLICATION_JSON_VALUE)
+		public String bar() {
+			return "{\"companyName\": \"FooBar\",\"employee\": [{\"name\": \"Lorem\",\"age\": \"42\"},{\"name\": \"Ipsum\",\"age\": \"24\"}]}";
+		}
+
 	}
 
 }