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