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-core/src/main/java/org/springframework/restdocs/generate/RestDocumentationGenerator.java

@@ -41,6 +41,7 @@ import org.springframework.util.Assert;
  * @param <REQ> the request type that can be handled
  * @param <RESP> the response type that can be handled
  * @author Andy Wilkinson
+ * @since 1.1
  */
 public final class RestDocumentationGenerator<REQ, RESP> {
 
@@ -205,11 +206,27 @@ public final class RestDocumentationGenerator<REQ, RESP> {
 	 * called.
 	 *
 	 * @param snippets the snippets to add
+	 * @deprecated since 1.1 in favor of {@link #withSnippets(Snippet...)}
 	 */
+	@Deprecated
 	public void addSnippets(Snippet... snippets) {
 		this.additionalSnippets.addAll(Arrays.asList(snippets));
 	}
 
+	/**
+	 * Creates a new {@link RestDocumentationGenerator} with the same configuration as
+	 * this one other than its snippets. The new generator will use the given
+	 * {@code snippets}.
+	 *
+	 * @param snippets the snippets
+	 * @return the new generator
+	 */
+	public RestDocumentationGenerator<REQ, RESP> withSnippets(Snippet... snippets) {
+		return new RestDocumentationGenerator<>(this.identifier, this.requestConverter,
+				this.responseConverter, this.requestPreprocessor,
+				this.responsePreprocessor, snippets);
+	}
+
 	@SuppressWarnings("unchecked")
 	private List<Snippet> getSnippets(Map<String, Object> configuration) {
 		List<Snippet> combinedSnippets = new ArrayList<>(this.snippets);

spring-restdocs-core/src/test/java/org/springframework/restdocs/RestDocumentationGeneratorTests.java

@@ -35,6 +35,8 @@ import org.springframework.restdocs.operation.OperationResponse;
 import org.springframework.restdocs.operation.OperationResponseFactory;
 import org.springframework.restdocs.operation.RequestConverter;
 import org.springframework.restdocs.operation.ResponseConverter;
+import org.springframework.restdocs.operation.preprocess.OperationRequestPreprocessor;
+import org.springframework.restdocs.operation.preprocess.OperationResponsePreprocessor;
 import org.springframework.restdocs.snippet.Snippet;
 
 import static org.hamcrest.CoreMatchers.equalTo;
@@ -43,6 +45,7 @@ import static org.junit.Assert.assertThat;
 import static org.mockito.BDDMockito.given;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoMoreInteractions;
 
 /**
  * Tests for {@link RestDocumentationGenerator}.
@@ -105,6 +108,7 @@ public class RestDocumentationGeneratorTests {
 	}
 
 	@Test
+	@Deprecated
 	public void additionalSnippetsAreCalled() throws IOException {
 		given(this.requestConverter.convert(this.request))
 				.willReturn(this.operationRequest);
@@ -123,6 +127,33 @@ public class RestDocumentationGeneratorTests {
 		verifySnippetInvocation(additionalSnippet2, configuration);
 	}
 
+	@Test
+	public void newGeneratorOnlyCallsItsSnippets() throws IOException {
+		OperationRequestPreprocessor requestPreprocessor = mock(
+				OperationRequestPreprocessor.class);
+		OperationResponsePreprocessor responsePreprocessor = mock(
+				OperationResponsePreprocessor.class);
+		given(this.requestConverter.convert(this.request))
+				.willReturn(this.operationRequest);
+		given(this.responseConverter.convert(this.response))
+				.willReturn(this.operationResponse);
+		given(requestPreprocessor.preprocess(this.operationRequest))
+				.willReturn(this.operationRequest);
+		given(responsePreprocessor.preprocess(this.operationResponse))
+				.willReturn(this.operationResponse);
+		Snippet additionalSnippet1 = mock(Snippet.class);
+		Snippet additionalSnippet2 = mock(Snippet.class);
+		RestDocumentationGenerator<Object, Object> generator = new RestDocumentationGenerator<>(
+				"id", this.requestConverter, this.responseConverter, requestPreprocessor,
+				responsePreprocessor, this.snippet);
+		HashMap<String, Object> configuration = new HashMap<>();
+		generator.withSnippets(additionalSnippet1, additionalSnippet2)
+				.handle(this.request, this.response, configuration);
+		verifyNoMoreInteractions(this.snippet);
+		verifySnippetInvocation(additionalSnippet1, configuration);
+		verifySnippetInvocation(additionalSnippet2, configuration);
+	}
+
 	private void verifySnippetInvocation(Snippet snippet, Map<String, Object> attributes)
 			throws IOException {
 		verifySnippetInvocation(snippet, attributes, 1);