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-core/src/test/java/org/springframework/restdocs/hypermedia/LinksSnippetTests.java

@@ -65,6 +65,17 @@ public class LinksSnippetTests {
 				"undocumented-link", this.snippet.getOutputDirectory()).build());
 	}
 
+	@Test
+	public void ignoredLink() throws IOException {
+		this.snippet.expectLinks("ignored-link").withContents(
+				tableWithHeader("Relation", "Description").row("b", "Link b"));
+		new LinksSnippet(new StubLinkExtractor().withLinks(new Link("a", "alpha"),
+				new Link("b", "bravo")), Arrays.asList(new LinkDescriptor("a").ignored(),
+				new LinkDescriptor("b").description("Link b")))
+				.document(new OperationBuilder("ignored-link", this.snippet
+						.getOutputDirectory()).build());
+	}
+
 	@Test
 	public void missingLink() throws IOException {
 		this.thrown.expect(SnippetException.class);

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

@@ -98,6 +98,19 @@ public class RequestFieldsSnippetTests {
 						.content("{\"a\": 5}").build());
 	}
 
+	@Test
+	public void ignoredRequestField() throws IOException {
+		this.snippet.expectRequestFields("ignored-request-field").withContents(
+				tableWithHeader("Path", "Type", "Description").row("b", "Number",
+						"Field b"));
+
+		new RequestFieldsSnippet(Arrays.asList(fieldWithPath("a").ignored(),
+				fieldWithPath("b").description("Field b")))
+				.document(new OperationBuilder("ignored-request-field", this.snippet
+						.getOutputDirectory()).request("http://localhost")
+						.content("{\"a\": 5, \"b\": 4}").build());
+	}
+
 	@Test
 	public void missingRequestField() throws IOException {
 		this.thrown.expect(SnippetException.class);

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

@@ -106,6 +106,19 @@ public class ResponseFieldsSnippetTests {
 						.content("[\"a\", \"b\", \"c\"]").build());
 	}
 
+	@Test
+	public void ignoredResponseField() throws IOException {
+		this.snippet.expectResponseFields("ignored-response-field").withContents(
+				tableWithHeader("Path", "Type", "Description").row("b", "Number",
+						"Field b"));
+
+		new ResponseFieldsSnippet(Arrays.asList(fieldWithPath("a").ignored(),
+				fieldWithPath("b").description("Field b")))
+				.document(new OperationBuilder("ignored-response-field", this.snippet
+						.getOutputDirectory()).response().content("{\"a\": 5, \"b\": 4}")
+						.build());
+	}
+
 	@Test
 	public void responseFieldsWithCustomDescriptorAttributes() throws IOException {
 		TemplateResourceResolver resolver = mock(TemplateResourceResolver.class);

spring-restdocs-core/src/test/java/org/springframework/restdocs/request/PathParametersSnippetTests.java

@@ -104,6 +104,18 @@ public class PathParametersSnippetTests {
 				"org.springframework.restdocs.urlTemplate", "/{a}/{b}").build());
 	}
 
+	@Test
+	public void ignoredPathParameter() throws IOException {
+		this.snippet.expectPathParameters("ignored-path-parameter").withContents(
+				tableWithTitleAndHeader("/{a}/{b}", "Parameter", "Description").row("b",
+						"two"));
+		new PathParametersSnippet(Arrays.asList(parameterWithName("a").ignored(),
+				parameterWithName("b").description("two")))
+				.document(new OperationBuilder("ignored-path-parameter", this.snippet
+						.getOutputDirectory()).attribute(
+						"org.springframework.restdocs.urlTemplate", "/{a}/{b}").build());
+	}
+
 	@Test
 	public void pathParametersWithQueryString() throws IOException {
 		this.snippet.expectPathParameters("path-parameters-with-query-string")

spring-restdocs-core/src/test/java/org/springframework/restdocs/request/RequestParametersSnippetTests.java

@@ -102,6 +102,17 @@ public class RequestParametersSnippetTests {
 				.build());
 	}
 
+	@Test
+	public void ignoredRequestParameter() throws IOException {
+		this.snippet.expectRequestParameters("ignored-request-parameter").withContents(
+				tableWithHeader("Parameter", "Description").row("b", "two"));
+		new RequestParametersSnippet(Arrays.asList(parameterWithName("a").ignored(),
+				parameterWithName("b").description("two")))
+				.document(new OperationBuilder("ignored-request-parameter", this.snippet
+						.getOutputDirectory()).request("http://localhost")
+						.param("a", "bravo").param("b", "bravo").build());
+	}
+
 	@Test
 	public void requestParametersWithCustomDescriptorAttributes() throws IOException {
 		TemplateResourceResolver resolver = mock(TemplateResourceResolver.class);