Add support for reusing a snippet to document common elements

This commit updates all of the Snippet implementations that take one
or more descriptors to provide an and method that can be used to
create a new Snippet that has additional descriptors.

Closes gh-168

spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/HeaderDocumentation.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2015 the original author or authors.
+ * Copyright 2014-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -55,7 +55,7 @@ public abstract class HeaderDocumentation {
 	 * @return the snippet that will document the request headers
 	 * @see #headerWithName(String)
 	 */
-	public static Snippet requestHeaders(HeaderDescriptor... descriptors) {
+	public static RequestHeadersSnippet requestHeaders(HeaderDescriptor... descriptors) {
 		return new RequestHeadersSnippet(Arrays.asList(descriptors));
 	}
 
@@ -72,7 +72,7 @@ public abstract class HeaderDocumentation {
 	 * @return the snippet that will document the request headers
 	 * @see #headerWithName(String)
 	 */
-	public static Snippet requestHeaders(Map<String, Object> attributes,
+	public static RequestHeadersSnippet requestHeaders(Map<String, Object> attributes,
 			HeaderDescriptor... descriptors) {
 		return new RequestHeadersSnippet(Arrays.asList(descriptors), attributes);
 	}
@@ -88,7 +88,8 @@ public abstract class HeaderDocumentation {
 	 * @return the snippet that will document the response headers
 	 * @see #headerWithName(String)
 	 */
-	public static Snippet responseHeaders(HeaderDescriptor... descriptors) {
+	public static ResponseHeadersSnippet responseHeaders(
+			HeaderDescriptor... descriptors) {
 		return new ResponseHeadersSnippet(Arrays.asList(descriptors));
 	}
 
@@ -106,7 +107,7 @@ public abstract class HeaderDocumentation {
 	 * @return the snippet that will document the response headers
 	 * @see #headerWithName(String)
 	 */
-	public static Snippet responseHeaders(Map<String, Object> attributes,
+	public static ResponseHeadersSnippet responseHeaders(Map<String, Object> attributes,
 			HeaderDescriptor... descriptors) {
 		return new ResponseHeadersSnippet(Arrays.asList(descriptors), attributes);
 	}

spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/RequestHeadersSnippet.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2015 the original author or authors.
+ * Copyright 2014-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,6 +16,8 @@
 
 package org.springframework.restdocs.headers;
 
+import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -27,6 +29,7 @@ import org.springframework.restdocs.snippet.Snippet;
  * A {@link Snippet} that documents the headers in a request.
  *
  * @author Andreas Evers
+ * @author Andy Wilkinson
  * @see HeaderDocumentation#requestHeaders(HeaderDescriptor...)
  * @see HeaderDocumentation#requestHeaders(Map, HeaderDescriptor...)
  */
@@ -60,4 +63,18 @@ public class RequestHeadersSnippet extends AbstractHeadersSnippet {
 		return operation.getRequest().getHeaders().keySet();
 	}
 
+	/**
+	 * Returns a new {@code RequestHeadersSnippet} configured with this snippet's
+	 * attributes and its descriptors combined with the given
+	 * {@code additionalDescriptors}.
+	 * @param additionalDescriptors the additional descriptors
+	 * @return the new snippet
+	 */
+	public RequestHeadersSnippet and(HeaderDescriptor... additionalDescriptors) {
+		List<HeaderDescriptor> combinedDescriptors = new ArrayList<>();
+		combinedDescriptors.addAll(this.getHeaderDescriptors());
+		combinedDescriptors.addAll(Arrays.asList(additionalDescriptors));
+		return new RequestHeadersSnippet(combinedDescriptors, getAttributes());
+	}
+
 }

spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/ResponseHeadersSnippet.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2015 the original author or authors.
+ * Copyright 2014-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,6 +16,8 @@
 
 package org.springframework.restdocs.headers;
 
+import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -27,6 +29,7 @@ import org.springframework.restdocs.snippet.Snippet;
  * A {@link Snippet} that documents the headers in a response.
  *
  * @author Andreas Evers
+ * @author Andy Wilkinson
  * @see HeaderDocumentation#responseHeaders(HeaderDescriptor...)
  * @see HeaderDocumentation#responseHeaders(Map, HeaderDescriptor...)
  */
@@ -60,4 +63,18 @@ public class ResponseHeadersSnippet extends AbstractHeadersSnippet {
 		return operation.getResponse().getHeaders().keySet();
 	}
 
+	/**
+	 * Returns a new {@code ResponseHeadersSnippet} configured with this snippet's
+	 * attributes and its descriptors combined with the given
+	 * {@code additionalDescriptors}.
+	 * @param additionalDescriptors the additional descriptors
+	 * @return the new snippet
+	 */
+	public final ResponseHeadersSnippet and(HeaderDescriptor... additionalDescriptors) {
+		List<HeaderDescriptor> combinedDescriptors = new ArrayList<>();
+		combinedDescriptors.addAll(this.getHeaderDescriptors());
+		combinedDescriptors.addAll(Arrays.asList(additionalDescriptors));
+		return new ResponseHeadersSnippet(combinedDescriptors, getAttributes());
+	}
+
 }

spring-restdocs-core/src/main/java/org/springframework/restdocs/http/HttpDocumentation.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2015 the original author or authors.
+ * Copyright 2014-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,8 +18,6 @@ package org.springframework.restdocs.http;
 
 import java.util.Map;
 
-import org.springframework.restdocs.snippet.Snippet;
-
 /**
  * Static factory methods for documenting a RESTful API's HTTP requests.
  *
@@ -38,7 +36,7 @@ public abstract class HttpDocumentation {
 	 *
 	 * @return the snippet that will document the HTTP request
 	 */
-	public static Snippet httpRequest() {
+	public static HttpRequestSnippet httpRequest() {
 		return new HttpRequestSnippet();
 	}
 
@@ -50,7 +48,7 @@ public abstract class HttpDocumentation {
 	 * @param attributes the attributes
 	 * @return the snippet that will document the HTTP request
 	 */
-	public static Snippet httpRequest(Map<String, Object> attributes) {
+	public static HttpRequestSnippet httpRequest(Map<String, Object> attributes) {
 		return new HttpRequestSnippet(attributes);
 	}
 
@@ -60,7 +58,7 @@ public abstract class HttpDocumentation {
 	 *
 	 * @return the snippet that will document the HTTP response
 	 */
-	public static Snippet httpResponse() {
+	public static HttpResponseSnippet httpResponse() {
 		return new HttpResponseSnippet();
 	}
 
@@ -72,7 +70,7 @@ public abstract class HttpDocumentation {
 	 * @param attributes the attributes
 	 * @return the snippet that will document the HTTP response
 	 */
-	public static Snippet httpResponse(Map<String, Object> attributes) {
+	public static HttpResponseSnippet httpResponse(Map<String, Object> attributes) {
 		return new HttpResponseSnippet(attributes);
 	}
 

spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/HypermediaDocumentation.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2015 the original author or authors.
+ * Copyright 2014-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,8 +19,6 @@ package org.springframework.restdocs.hypermedia;
 import java.util.Arrays;
 import java.util.Map;
 
-import org.springframework.restdocs.snippet.Snippet;
-
 /**
  * Static factory methods for documenting a RESTful API that utilizes Hypermedia.
  *
@@ -59,7 +57,7 @@ public abstract class HypermediaDocumentation {
 	 * @param descriptors the descriptions of the response's links
 	 * @return the snippet that will document the links
 	 */
-	public static Snippet links(LinkDescriptor... descriptors) {
+	public static LinksSnippet links(LinkDescriptor... descriptors) {
 		return new LinksSnippet(new ContentTypeLinkExtractor(),
 				Arrays.asList(descriptors));
 	}
@@ -83,7 +81,7 @@ public abstract class HypermediaDocumentation {
 	 * @param descriptors the descriptions of the response's links
 	 * @return the snippet that will document the links
 	 */
-	public static Snippet links(Map<String, Object> attributes,
+	public static LinksSnippet links(Map<String, Object> attributes,
 			LinkDescriptor... descriptors) {
 		return new LinksSnippet(new ContentTypeLinkExtractor(),
 				Arrays.asList(descriptors), attributes);
@@ -107,7 +105,7 @@ public abstract class HypermediaDocumentation {
 	 * @param descriptors the descriptions of the response's links
 	 * @return the snippet that will document the links
 	 */
-	public static Snippet links(LinkExtractor linkExtractor,
+	public static LinksSnippet links(LinkExtractor linkExtractor,
 			LinkDescriptor... descriptors) {
 		return new LinksSnippet(linkExtractor, Arrays.asList(descriptors));
 	}
@@ -132,7 +130,7 @@ public abstract class HypermediaDocumentation {
 	 * @param descriptors the descriptions of the response's links
 	 * @return the snippet that will document the links
 	 */
-	public static Snippet links(LinkExtractor linkExtractor,
+	public static LinksSnippet links(LinkExtractor linkExtractor,
 			Map<String, Object> attributes, LinkDescriptor... descriptors) {
 		return new LinksSnippet(linkExtractor, Arrays.asList(descriptors), attributes);
 	}

spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/LinksSnippet.java

@@ -18,6 +18,7 @@ package org.springframework.restdocs.hypermedia;
 
 import java.io.IOException;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.LinkedHashMap;
@@ -170,4 +171,18 @@ public class LinksSnippet extends TemplatedSnippet {
 		return model;
 	}
 
+	/**
+	 * Returns a new {@code RequestHeadersSnippet} configured with this snippet's link
+	 * extractor and attributes, and its descriptors combined with the given
+	 * {@code additionalDescriptors}.
+	 * @param additionalDescriptors the additional descriptors
+	 * @return the new snippet
+	 */
+	public LinksSnippet and(LinkDescriptor... additionalDescriptors) {
+		List<LinkDescriptor> combinedDescriptors = new ArrayList<>();
+		combinedDescriptors.addAll(this.descriptorsByRel.values());
+		combinedDescriptors.addAll(Arrays.asList(additionalDescriptors));
+		return new LinksSnippet(this.linkExtractor, combinedDescriptors, getAttributes());
+	}
+
 }

spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/PayloadDocumentation.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2015 the original author or authors.
+ * Copyright 2014-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,8 +19,6 @@ package org.springframework.restdocs.payload;
 import java.util.Arrays;
 import java.util.Map;
 
-import org.springframework.restdocs.snippet.Snippet;
-
 /**
  * Static factory methods for documenting a RESTful API's request and response payloads.
  *
@@ -117,7 +115,7 @@ public abstract class PayloadDocumentation {
 	 * @return the snippet that will document the fields
 	 * @see #fieldWithPath(String)
 	 */
-	public static Snippet requestFields(FieldDescriptor... descriptors) {
+	public static RequestFieldsSnippet requestFields(FieldDescriptor... descriptors) {
 		return new RequestFieldsSnippet(Arrays.asList(descriptors));
 	}
 
@@ -142,7 +140,7 @@ public abstract class PayloadDocumentation {
 	 * @return the snippet that will document the fields
 	 * @see #fieldWithPath(String)
 	 */
-	public static Snippet requestFields(Map<String, Object> attributes,
+	public static RequestFieldsSnippet requestFields(Map<String, Object> attributes,
 			FieldDescriptor... descriptors) {
 		return new RequestFieldsSnippet(Arrays.asList(descriptors), attributes);
 	}
@@ -167,7 +165,7 @@ public abstract class PayloadDocumentation {
 	 * @return the snippet that will document the fields
 	 * @see #fieldWithPath(String)
 	 */
-	public static Snippet responseFields(FieldDescriptor... descriptors) {
+	public static ResponseFieldsSnippet responseFields(FieldDescriptor... descriptors) {
 		return new ResponseFieldsSnippet(Arrays.asList(descriptors));
 	}
 
@@ -192,7 +190,7 @@ public abstract class PayloadDocumentation {
 	 * @return the snippet that will document the fields
 	 * @see #fieldWithPath(String)
 	 */
-	public static Snippet responseFields(Map<String, Object> attributes,
+	public static ResponseFieldsSnippet responseFields(Map<String, Object> attributes,
 			FieldDescriptor... descriptors) {
 		return new ResponseFieldsSnippet(Arrays.asList(descriptors), attributes);
 	}

spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/RequestFieldsSnippet.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2015 the original author or authors.
+ * Copyright 2014-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,6 +17,8 @@
 package org.springframework.restdocs.payload;
 
 import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
 
@@ -66,4 +68,18 @@ public class RequestFieldsSnippet extends AbstractFieldsSnippet {
 		return operation.getRequest().getContent();
 	}
 
+	/**
+	 * Returns a new {@code RequestFieldsSnippet} configured with this snippet's
+	 * attributes and its descriptors combined with the given
+	 * {@code additionalDescriptors}.
+	 * @param additionalDescriptors the additional descriptors
+	 * @return the new snippet
+	 */
+	public RequestFieldsSnippet and(FieldDescriptor... additionalDescriptors) {
+		List<FieldDescriptor> combinedDescriptors = new ArrayList<>();
+		combinedDescriptors.addAll(getFieldDescriptors());
+		combinedDescriptors.addAll(Arrays.asList(additionalDescriptors));
+		return new RequestFieldsSnippet(combinedDescriptors, this.getAttributes());
+	}
+
 }

spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/ResponseFieldsSnippet.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2015 the original author or authors.
+ * Copyright 2014-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,6 +17,8 @@
 package org.springframework.restdocs.payload;
 
 import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
 
@@ -66,4 +68,18 @@ public class ResponseFieldsSnippet extends AbstractFieldsSnippet {
 		return operation.getResponse().getContent();
 	}
 
+	/**
+	 * Returns a new {@code ResponseFieldsSnippet} configured with this snippet's
+	 * attributes and its descriptors combined with the given
+	 * {@code additionalDescriptors}.
+	 * @param additionalDescriptors the additional descriptors
+	 * @return the new snippet
+	 */
+	public ResponseFieldsSnippet and(FieldDescriptor... additionalDescriptors) {
+		List<FieldDescriptor> combinedDescriptors = new ArrayList<>();
+		combinedDescriptors.addAll(getFieldDescriptors());
+		combinedDescriptors.addAll(Arrays.asList(additionalDescriptors));
+		return new ResponseFieldsSnippet(combinedDescriptors, this.getAttributes());
+	}
+
 }

spring-restdocs-core/src/main/java/org/springframework/restdocs/request/AbstractParametersSnippet.java

@@ -122,11 +122,24 @@ public abstract class AbstractParametersSnippet extends TemplatedSnippet {
 	 * {@link ParameterDescriptor#getName()}.
 	 *
 	 * @return the map of path descriptors
+	 * @deprecated since 1.1.0 in favor of {@link #getParameterDescriptors()}
 	 */
+	@Deprecated
 	protected final Map<String, ParameterDescriptor> getFieldDescriptors() {
 		return this.descriptorsByName;
 	}
 
+	/**
+	 * Returns a {@code Map} of {@link ParameterDescriptor ParameterDescriptors} that will
+	 * be used to generate the documentation key by their
+	 * {@link ParameterDescriptor#getName()}.
+	 *
+	 * @return the map of path descriptors
+	 */
+	protected final Map<String, ParameterDescriptor> getParameterDescriptors() {
+		return this.descriptorsByName;
+	}
+
 	/**
 	 * Returns a model for the given {@code descriptor}.
 	 *

spring-restdocs-core/src/main/java/org/springframework/restdocs/request/PathParametersSnippet.java

@@ -16,6 +16,8 @@
 
 package org.springframework.restdocs.request;
 
+import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
@@ -122,4 +124,18 @@ public class PathParametersSnippet extends AbstractParametersSnippet {
 		throw new SnippetException(message);
 	}
 
+	/**
+	 * Returns a new {@code PathParametersSnippet} configured with this snippet's
+	 * attributes and its descriptors combined with the given
+	 * {@code additionalDescriptors}.
+	 * @param additionalDescriptors the additional descriptors
+	 * @return the new snippet
+	 */
+	public PathParametersSnippet and(ParameterDescriptor... additionalDescriptors) {
+		List<ParameterDescriptor> combinedDescriptors = new ArrayList<>();
+		combinedDescriptors.addAll(getParameterDescriptors().values());
+		combinedDescriptors.addAll(Arrays.asList(additionalDescriptors));
+		return new PathParametersSnippet(combinedDescriptors, this.getAttributes());
+	}
+
 }

spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestDocumentation.java

@@ -20,7 +20,6 @@ import java.util.Arrays;
 import java.util.Map;
 
 import org.springframework.restdocs.operation.OperationRequest;
-import org.springframework.restdocs.snippet.Snippet;
 
 /**
  * Static factory methods for documenting aspects of a request sent to a RESTful API.
@@ -61,7 +60,8 @@ public abstract class RequestDocumentation {
 	 * @param descriptors the descriptions of the parameters in the request's path
 	 * @return the snippet that will document the parameters
 	 */
-	public static Snippet pathParameters(ParameterDescriptor... descriptors) {
+	public static PathParametersSnippet pathParameters(
+			ParameterDescriptor... descriptors) {
 		return new PathParametersSnippet(Arrays.asList(descriptors));
 	}
 
@@ -84,7 +84,7 @@ public abstract class RequestDocumentation {
 	 * @param descriptors the descriptions of the parameters in the request's path
 	 * @return the snippet that will document the parameters
 	 */
-	public static Snippet pathParameters(Map<String, Object> attributes,
+	public static PathParametersSnippet pathParameters(Map<String, Object> attributes,
 			ParameterDescriptor... descriptors) {
 		return new PathParametersSnippet(Arrays.asList(descriptors), attributes);
 	}
@@ -107,7 +107,8 @@ public abstract class RequestDocumentation {
 	 * @return the snippet
 	 * @see OperationRequest#getParameters()
 	 */
-	public static Snippet requestParameters(ParameterDescriptor... descriptors) {
+	public static RequestParametersSnippet requestParameters(
+			ParameterDescriptor... descriptors) {
 		return new RequestParametersSnippet(Arrays.asList(descriptors));
 	}
 
@@ -131,8 +132,8 @@ public abstract class RequestDocumentation {
 	 * @return the snippet that will document the parameters
 	 * @see OperationRequest#getParameters()
 	 */
-	public static Snippet requestParameters(Map<String, Object> attributes,
-			ParameterDescriptor... descriptors) {
+	public static RequestParametersSnippet requestParameters(
+			Map<String, Object> attributes, ParameterDescriptor... descriptors) {
 		return new RequestParametersSnippet(Arrays.asList(descriptors), attributes);
 	}
 

spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestParametersSnippet.java

@@ -16,6 +16,8 @@
 
 package org.springframework.restdocs.request;
 
+import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -84,4 +86,18 @@ public class RequestParametersSnippet extends AbstractParametersSnippet {
 		return operation.getRequest().getParameters().keySet();
 	}
 
+	/**
+	 * Returns a new {@code RequestParametersSnippet} configured with this snippet's
+	 * attributes and its descriptors combined with the given
+	 * {@code additionalDescriptors}.
+	 * @param additionalDescriptors the additional descriptors
+	 * @return the new snippet
+	 */
+	public RequestParametersSnippet and(ParameterDescriptor... additionalDescriptors) {
+		List<ParameterDescriptor> combinedDescriptors = new ArrayList<>();
+		combinedDescriptors.addAll(getParameterDescriptors().values());
+		combinedDescriptors.addAll(Arrays.asList(additionalDescriptors));
+		return new RequestParametersSnippet(combinedDescriptors, this.getAttributes());
+	}
+
 }