Introduce relaxed snippets that don’t fail when item is not documented

Previously, many of the snippets would fail when something wasn’t
documented. This worked well when writing exhaustive API documentation,
but was cumbersome when trying to document a scenario that might only
being interested in a subset of the links, response fields, etc. It was
necessary to mark things that were not of interest as being ignored.

This commit introduces a relaxed variant of several snippets. A relaxed
snippet will not fail if something has not been documented. Instead,
the undocumented thing will be ignored. If something has been documented
but it does not exist a failure will still occur.

Closes gh-175

spring-restdocs-core/src/test/java/org/springframework/restdocs/hypermedia/LinksSnippetTests.java

@@ -56,6 +56,17 @@ public class LinksSnippetTests extends AbstractSnippetTests {
 								.document(operationBuilder("ignored-link").build());
 	}
 
+	@Test
+	public void allUndocumentedLinksCanBeIgnored() throws IOException {
+		this.snippet.expectLinks("ignore-all-undocumented").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("b").description("Link b")), true)
+						.document(operationBuilder("ignore-all-undocumented").build());
+	}
+
 	@Test
 	public void documentedOptionalLink() throws IOException {
 		this.snippet.expectLinks("documented-optional-link").withContents(

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

@@ -93,6 +93,19 @@ public class RequestFieldsSnippetTests extends AbstractSnippetTests {
 								.content("{\"a\": 5, \"b\": 4}").build());
 	}
 
+	@Test
+	public void allUndocumentedRequestFieldsCanBeIgnored() throws IOException {
+		this.snippet.expectRequestFields("ignore-all-undocumented")
+				.withContents(tableWithHeader("Path", "Type", "Description").row("b",
+						"Number", "Field b"));
+
+		new RequestFieldsSnippet(Arrays.asList(fieldWithPath("b").description("Field b")),
+				true).document(
+						operationBuilder("ignore-all-undocumented")
+								.request("http://localhost")
+								.content("{\"a\": 5, \"b\": 4}").build());
+	}
+
 	@Test
 	public void requestFieldsWithCustomAttributes() throws IOException {
 		TemplateResourceResolver resolver = mock(TemplateResourceResolver.class);

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

@@ -105,6 +105,18 @@ public class ResponseFieldsSnippetTests extends AbstractSnippetTests {
 								.content("{\"a\": 5, \"b\": 4}").build());
 	}
 
+	@Test
+	public void allUndocumentedFieldsCanBeIgnored() throws IOException {
+		this.snippet.expectResponseFields("ignore-all-undocumented")
+				.withContents(tableWithHeader("Path", "Type", "Description").row("b",
+						"Number", "Field b"));
+
+		new ResponseFieldsSnippet(
+				Arrays.asList(fieldWithPath("b").description("Field b")), true)
+						.document(operationBuilder("ignore-all-undocumented").response()
+								.content("{\"a\": 5, \"b\": 4}").build());
+	}
+
 	@Test
 	public void responseFieldsWithCustomAttributes() throws IOException {
 		TemplateResourceResolver resolver = mock(TemplateResourceResolver.class);

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

@@ -71,6 +71,19 @@ public class PathParametersSnippetTests extends AbstractSnippetTests {
 								"/{a}/{b}").build());
 	}
 
+	@Test
+	public void allUndocumentedPathParametersCanBeIgnored() throws IOException {
+		this.snippet.expectPathParameters("ignore-all-undocumented").withContents(
+				tableWithTitleAndHeader(getTitle(), "Parameter", "Description").row("b",
+						"two"));
+		new PathParametersSnippet(
+				Arrays.asList(parameterWithName("b").description("two")),
+				true).document(operationBuilder("ignore-all-undocumented")
+						.attribute(RestDocumentationGenerator.ATTRIBUTE_NAME_URL_TEMPLATE,
+								"/{a}/{b}")
+						.build());
+	}
+
 	@Test
 	public void missingOptionalPathParameter() throws IOException {
 		this.snippet

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

@@ -80,6 +80,17 @@ public class RequestParametersSnippetTests extends AbstractSnippetTests {
 								.param("b", "bravo").build());
 	}
 
+	@Test
+	public void allUndocumentedRequestParametersCanBeIgnored() throws IOException {
+		this.snippet.expectRequestParameters("ignore-all-undocumented").withContents(
+				tableWithHeader("Parameter", "Description").row("b", "two"));
+		new RequestParametersSnippet(
+				Arrays.asList(parameterWithName("b").description("two")), true)
+						.document(operationBuilder("ignore-all-undocumented")
+								.request("http://localhost").param("a", "bravo")
+								.param("b", "bravo").build());
+	}
+
 	@Test
 	public void missingOptionalRequestParameter() throws IOException {
 		this.snippet.expectRequestParameters("missing-optional-request-parameter")