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/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);