Improve the API for generating additional snippets

Previously, if alwaysDo was used and the user wanted to generate
one or more additional snippets when calling perform a separate call
to `snippets` was made prior to calling `perform`. This had two
problems:

 - it required the result handler to be stateful (see gh-243)
 - it wasn't clear that the additional snippets would be produced when
   a subsequent call to perform was made

This commit introduces a new API that allows the additional snippets
to be specified within the MockMvc call. The old API has been
deprecated and will be removed in 2.0.

Closes gh-249

spring-restdocs-restassured/src/test/java/org/springframework/restdocs/restassured/RestAssuredRestDocumentationIntegrationTests.java

@@ -52,6 +52,8 @@ import static org.hamcrest.CoreMatchers.equalTo;
 import static org.hamcrest.CoreMatchers.is;
 import static org.junit.Assert.assertThat;
 import static org.junit.Assert.assertTrue;
+import static org.springframework.restdocs.headers.HeaderDocumentation.headerWithName;
+import static org.springframework.restdocs.headers.HeaderDocumentation.responseHeaders;
 import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.linkWithRel;
 import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.links;
 import static org.springframework.restdocs.operation.preprocess.Preprocessors.maskLinks;
@@ -240,6 +242,23 @@ public class RestAssuredRestDocumentationIntegrationTests {
 				"http-response.adoc", "curl-request.adoc");
 	}
 
+	@Test
+	public void additionalSnippets() throws Exception {
+		RestDocumentationFilter documentation = document("{method-name}-{step}");
+		RequestSpecification spec = new RequestSpecBuilder().setPort(this.port)
+				.addFilter(documentationConfiguration(this.restDocumentation))
+				.addFilter(documentation).build();
+		given(spec)
+				.filter(documentation
+						.document(responseHeaders(headerWithName("a").description("one"),
+								headerWithName("Foo").description("two"))))
+				.get("/").then().statusCode(200);
+		assertExpectedSnippetFilesExist(
+				new File("build/generated-snippets/additional-snippets-1/"),
+				"http-request.adoc", "http-response.adoc", "curl-request.adoc",
+				"response-headers.adoc");
+	}
+
 	@Test
 	public void preprocessedRequest() throws Exception {
 		Pattern pattern = Pattern.compile("(\"alpha\")");