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-mockmvc/src/main/java/org/springframework/restdocs/mockmvc/RestDocumentationResultHandler.java

@@ -16,6 +16,7 @@
 
 package org.springframework.restdocs.mockmvc;
 
+import java.util.HashMap;
 import java.util.Map;
 
 import org.springframework.mock.web.MockHttpServletRequest;
@@ -59,10 +60,44 @@ public class RestDocumentationResultHandler implements ResultHandler {
 	 *
 	 * @param snippets the snippets to add
 	 * @return this {@code RestDocumentationResultHandler}
+	 * @deprecated since 1.1 in favor of {@link #document(Snippet...)}
 	 */
+	@Deprecated
 	public RestDocumentationResultHandler snippets(Snippet... snippets) {
 		this.delegate.addSnippets(snippets);
 		return this;
 	}
 
+	/**
+	 * Creates a new {@link RestDocumentationResultHandler} that will produce
+	 * documentation using the given {@code snippets}.
+	 *
+	 * @param snippets the snippets
+	 * @return the new result handler
+	 */
+	public RestDocumentationResultHandler document(Snippet... snippets) {
+		return new RestDocumentationResultHandler(this.delegate.withSnippets(snippets)) {
+
+			@Override
+			public void handle(MvcResult result) throws Exception {
+				@SuppressWarnings("unchecked")
+				Map<String, Object> configuration = new HashMap<>(
+						(Map<String, Object>) result.getRequest()
+								.getAttribute(ATTRIBUTE_NAME_CONFIGURATION));
+				configuration.remove(
+						RestDocumentationGenerator.ATTRIBUTE_NAME_DEFAULT_SNIPPETS);
+				getDelegate().handle(result.getRequest(), result.getResponse(),
+						configuration);
+			}
+		};
+	}
+
+	/**
+	 * Returns the {@link RestDocumentationGenerator} that is used as a delegate.
+	 *
+	 * @return the delegate
+	 */
+	protected final RestDocumentationGenerator<MockHttpServletRequest, MockHttpServletResponse> getDelegate() {
+		return this.delegate;
+	}
 }

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

@@ -56,6 +56,8 @@ import static org.hamcrest.CoreMatchers.is;
 import static org.junit.Assert.assertThat;
 import static org.junit.Assert.assertTrue;
 import static org.springframework.restdocs.cli.CliDocumentation.curlRequest;
+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.mockmvc.MockMvcRestDocumentation.document;
@@ -329,6 +331,24 @@ public class MockMvcRestDocumentationIntegrationTests {
 				"http-response.adoc", "curl-request.adoc");
 	}
 
+	@Test
+	public void alwaysDoWithAdditionalSnippets() throws Exception {
+		RestDocumentationResultHandler documentation = document("{method-name}-{step}");
+		MockMvc mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
+				.apply(documentationConfiguration(this.restDocumentation))
+				.alwaysDo(documentation).build();
+
+		mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
+				.andExpect(status().isOk()).andDo(documentation.document(
+						responseHeaders(headerWithName("a").description("one"))));
+
+		assertExpectedSnippetFilesExist(
+				new File(
+						"build/generated-snippets/always-do-with-additional-snippets-1/"),
+				"http-request.adoc", "http-response.adoc", "curl-request.adoc",
+				"response-headers.adoc");
+	}
+
 	@Test
 	public void preprocessedRequest() throws Exception {
 		MockMvc mockMvc = MockMvcBuilders.webAppContextSetup(this.context)