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/main/java/org/springframework/restdocs/restassured/RestDocumentationFilter.java

@@ -35,7 +35,7 @@ import org.springframework.util.Assert;
  *
  * @author Andy Wilkinson
  */
-public final class RestDocumentationFilter implements Filter {
+public class RestDocumentationFilter implements Filter {
 
 	static final String CONTEXT_KEY_CONFIGURATION = "org.springframework.restdocs.configuration";
 
@@ -48,10 +48,27 @@ public final class RestDocumentationFilter implements Filter {
 	}
 
 	@Override
-	public Response filter(FilterableRequestSpecification requestSpec,
+	public final Response filter(FilterableRequestSpecification requestSpec,
 			FilterableResponseSpecification responseSpec, FilterContext context) {
 		Response response = context.next(requestSpec, responseSpec);
 
+		Map<String, Object> configuration = getConfiguration(requestSpec, context);
+
+		this.delegate.handle(requestSpec, response, configuration);
+
+		return response;
+	}
+
+	/**
+	 * Returns the configuration that should be used when calling the delgate. The
+	 * configuration is derived from the given {@code requestSpec} and {@code context}.
+	 *
+	 * @param requestSpec the request specification
+	 * @param context the filter context
+	 * @return the configuration
+	 */
+	protected Map<String, Object> getConfiguration(
+			FilterableRequestSpecification requestSpec, FilterContext context) {
 		Map<String, Object> configuration = new HashMap<>(
 				context.<Map<String, Object>>getValue(CONTEXT_KEY_CONFIGURATION));
 		configuration.put(RestDocumentationContext.class.getName(),
@@ -59,10 +76,7 @@ public final class RestDocumentationFilter implements Filter {
 						RestDocumentationContext.class.getName()));
 		configuration.put(RestDocumentationGenerator.ATTRIBUTE_NAME_URL_TEMPLATE,
 				requestSpec.getUserDefinedPath());
-
-		this.delegate.handle(requestSpec, response, configuration);
-
-		return response;
+		return configuration;
 	}
 
 	/**
@@ -71,10 +85,35 @@ public final class RestDocumentationFilter implements Filter {
 	 *
 	 * @param snippets the snippets to add
 	 * @return this {@code RestDocumentationFilter}
+	 * @deprecated since 1.1 in favor of {@link #document(Snippet...)}
 	 */
-	public RestDocumentationFilter snippets(Snippet... snippets) {
+	@Deprecated
+	public final RestDocumentationFilter snippets(Snippet... snippets) {
 		this.delegate.addSnippets(snippets);
 		return this;
 	}
 
+	/**
+	 * Creates a new {@link RestDocumentationFilter} that will produce documentation using
+	 * the given {@code snippets}.
+	 *
+	 * @param snippets the snippets
+	 * @return the new result handler
+	 */
+	public final RestDocumentationFilter document(Snippet... snippets) {
+		return new RestDocumentationFilter(this.delegate.withSnippets(snippets)) {
+
+			@Override
+			protected Map<String, Object> getConfiguration(
+					FilterableRequestSpecification requestSpec, FilterContext context) {
+				Map<String, Object> configuration = super.getConfiguration(requestSpec,
+						context);
+				configuration.remove(
+						RestDocumentationGenerator.ATTRIBUTE_NAME_DEFAULT_SNIPPETS);
+				return configuration;
+			}
+
+		};
+	}
+
 }

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\")");