From 5edc27fc990b984c733d88850f9c971529846da8 Mon Sep 17 00:00:00 2001
From: Marcel Overdijk <marcel@overdijk.me>
Date: Tue, 24 May 2016 11:42:35 +0200
Subject: [PATCH 1/2] Allow descriptors to be provided as a List as well as via
 varags

Closes gh-247
---
 .../restdocs/headers/HeaderDocumentation.java |  69 +++++
 .../hypermedia/HypermediaDocumentation.java   | 195 ++++++++++++++
 .../payload/PayloadDocumentation.java         | 167 ++++++++++++
 .../request/RequestDocumentation.java         | 244 ++++++++++++++++++
 4 files changed, 675 insertions(+)

diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/HeaderDocumentation.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/HeaderDocumentation.java
index 1eb4f0f9..740f6a78 100644
--- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/HeaderDocumentation.java
+++ b/spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/HeaderDocumentation.java
@@ -17,6 +17,7 @@
 package org.springframework.restdocs.headers;
 
 import java.util.Arrays;
+import java.util.List;
 import java.util.Map;
 
 import org.springframework.restdocs.snippet.Snippet;
@@ -59,6 +60,21 @@ public abstract class HeaderDocumentation {
 		return new RequestHeadersSnippet(Arrays.asList(descriptors));
 	}
 
+	/**
+	 * Returns a new {@link Snippet} that will document the headers of the API operation's
+	 * request. The headers will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a header is documented, is not marked as optional, and is not present in the
+	 * request, a failure will occur.
+	 *
+	 * @param descriptors the descriptions of the request's headers
+	 * @return the snippet that will document the request headers
+	 * @see #headerWithName(String)
+	 */
+	public static RequestHeadersSnippet requestHeaders(List<HeaderDescriptor> descriptors) {
+		return new RequestHeadersSnippet(descriptors);
+	}
+
 	/**
 	 * Returns a new {@link Snippet} that will document the headers of the API
 	 * operations's request. The given {@code attributes} will be available during snippet
@@ -77,6 +93,24 @@ public abstract class HeaderDocumentation {
 		return new RequestHeadersSnippet(Arrays.asList(descriptors), attributes);
 	}
 
+	/**
+	 * Returns a new {@link Snippet} that will document the headers of the API
+	 * operations's request. The given {@code attributes} will be available during snippet
+	 * generation and the headers will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a header is documented, is not marked as optional, and is not present in the
+	 * request, a failure will occur.
+	 *
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the request's headers
+	 * @return the snippet that will document the request headers
+	 * @see #headerWithName(String)
+	 */
+	public static RequestHeadersSnippet requestHeaders(Map<String, Object> attributes,
+			List<HeaderDescriptor> descriptors) {
+		return new RequestHeadersSnippet(descriptors, attributes);
+	}
+
 	/**
 	 * Returns a new {@link Snippet} that will document the headers of the API operation's
 	 * response. The headers will be documented using the given {@code descriptors}.
@@ -93,6 +127,22 @@ public abstract class HeaderDocumentation {
 		return new ResponseHeadersSnippet(Arrays.asList(descriptors));
 	}
 
+	/**
+	 * Returns a new {@link Snippet} that will document the headers of the API operation's
+	 * response. The headers will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a header is documented, is not marked as optional, and is not present in the
+	 * request, a failure will occur.
+	 *
+	 * @param descriptors the descriptions of the response's headers
+	 * @return the snippet that will document the response headers
+	 * @see #headerWithName(String)
+	 */
+	public static ResponseHeadersSnippet responseHeaders(
+			List<HeaderDescriptor> descriptors) {
+		return new ResponseHeadersSnippet(descriptors);
+	}
+
 	/**
 	 * Returns a new {@link Snippet} that will document the headers of the API
 	 * operations's response. The given {@code attributes} will be available during
@@ -112,4 +162,23 @@ public abstract class HeaderDocumentation {
 		return new ResponseHeadersSnippet(Arrays.asList(descriptors), attributes);
 	}
 
+	/**
+	 * Returns a new {@link Snippet} that will document the headers of the API
+	 * operations's response. The given {@code attributes} will be available during
+	 * snippet generation and the headers will be documented using the given
+	 * {@code descriptors}.
+	 * <p>
+	 * If a header is documented, is not marked as optional, and is not present in the
+	 * response, a failure will occur.
+	 *
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the response's headers
+	 * @return the snippet that will document the response headers
+	 * @see #headerWithName(String)
+	 */
+	public static ResponseHeadersSnippet responseHeaders(Map<String, Object> attributes,
+			List<HeaderDescriptor> descriptors) {
+		return new ResponseHeadersSnippet(descriptors, attributes);
+	}
+
 }
diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/HypermediaDocumentation.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/HypermediaDocumentation.java
index 95f70b3b..a6098ce5 100644
--- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/HypermediaDocumentation.java
+++ b/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/HypermediaDocumentation.java
@@ -17,6 +17,7 @@
 package org.springframework.restdocs.hypermedia;
 
 import java.util.Arrays;
+import java.util.List;
 import java.util.Map;
 
 /**
@@ -66,6 +67,31 @@ public abstract class HypermediaDocumentation {
 				Arrays.asList(descriptors));
 	}
 
+	/**
+	 * Returns a new {@code Snippet} that will document the links in the API operation's
+	 * response. Links will be extracted from the response automatically based on its
+	 * content type and will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a link is present in the response, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a link
+	 * is documented, is not marked as optional, and is not present in the response, a
+	 * failure will also occur.
+	 * <p>
+	 * If you do not want to document a link, a link descriptor can be marked as
+	 * {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
+	 * generated snippet while avoiding the failure described above.
+	 * <p>
+	 * If a descriptor does not have a {@link LinkDescriptor#description(Object)
+	 * description}, the {@link Link#getTitle() title} of the link will be used. If the
+	 * link does not have a title a failure will occur.
+	 *
+	 * @param descriptors the descriptions of the response's links
+	 * @return the snippet that will document the links
+	 */
+	public static LinksSnippet links(List<LinkDescriptor> descriptors) {
+		return new LinksSnippet(new ContentTypeLinkExtractor(), descriptors);
+	}
+
 	/**
 	 * Returns a new {@code Snippet} that will document the links in the API operation's
 	 * response. Links will be extracted from the response automatically based on its
@@ -86,6 +112,25 @@ public abstract class HypermediaDocumentation {
 				Arrays.asList(descriptors), true);
 	}
 
+	/**
+	 * Returns a new {@code Snippet} that will document the links in the API operation's
+	 * response. Links will be extracted from the response automatically based on its
+	 * content type and will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a link is documented, is not marked as optional, and is not present in the
+	 * response, a failure will occur. Any undocumented links will be ignored.
+	 * <p>
+	 * If a descriptor does not have a {@link LinkDescriptor#description(Object)
+	 * description}, the {@link Link#getTitle() title} of the link will be used. If the
+	 * link does not have a title a failure will occur.
+	 *
+	 * @param descriptors the descriptions of the response's links
+	 * @return the snippet that will document the links
+	 */
+	public static LinksSnippet relaxedLinks(List<LinkDescriptor> descriptors) {
+		return new LinksSnippet(new ContentTypeLinkExtractor(), descriptors, true);
+	}
+
 	/**
 	 * Returns a new {@code Snippet} that will document the links in the API call's
 	 * response. The given {@code attributes} will be available during snippet generation.
@@ -115,6 +160,34 @@ public abstract class HypermediaDocumentation {
 				Arrays.asList(descriptors), attributes);
 	}
 
+	/**
+	 * Returns a new {@code Snippet} that will document the links in the API call's
+	 * response. The given {@code attributes} will be available during snippet generation.
+	 * Links will be extracted from the response automatically based on its content type
+	 * and will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a link is present in the response, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a link
+	 * is documented, is not marked as optional, and is not present in the response, a
+	 * failure will also occur.
+	 * <p>
+	 * If you do not want to document a link, a link descriptor can be marked as
+	 * {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
+	 * generated snippet while avoiding the failure described above.
+	 * <p>
+	 * If a descriptor does not have a {@link LinkDescriptor#description(Object)
+	 * description}, the {@link Link#getTitle() title} of the link will be used. If the
+	 * link does not have a title a failure will occur.
+	 *
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the response's links
+	 * @return the snippet that will document the links
+	 */
+	public static LinksSnippet links(Map<String, Object> attributes,
+			List<LinkDescriptor> descriptors) {
+		return new LinksSnippet(new ContentTypeLinkExtractor(), descriptors, attributes);
+	}
+
 	/**
 	 * Returns a new {@code Snippet} that will document the links in the API call's
 	 * response. The given {@code attributes} will be available during snippet generation.
@@ -138,6 +211,28 @@ public abstract class HypermediaDocumentation {
 				Arrays.asList(descriptors), attributes, true);
 	}
 
+	/**
+	 * Returns a new {@code Snippet} that will document the links in the API call's
+	 * response. The given {@code attributes} will be available during snippet generation.
+	 * Links will be extracted from the response automatically based on its content type
+	 * and will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a link is documented, is not marked as optional, and is not present in the
+	 * response, a failure will occur. Any undocumented links will be ignored.
+	 * <p>
+	 * If a descriptor does not have a {@link LinkDescriptor#description(Object)
+	 * description}, the {@link Link#getTitle() title} of the link will be used. If the
+	 * link does not have a title a failure will occur.
+	 *
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the response's links
+	 * @return the snippet that will document the links
+	 */
+	public static LinksSnippet relaxedLinks(Map<String, Object> attributes,
+											List<LinkDescriptor> descriptors) {
+		return new LinksSnippet(new ContentTypeLinkExtractor(), descriptors, attributes, true);
+	}
+
 	/**
 	 * Returns a new {@code Snippet} that will document the links in the API operation's
 	 * response. Links will be extracted from the response using the given
@@ -165,6 +260,33 @@ public abstract class HypermediaDocumentation {
 		return new LinksSnippet(linkExtractor, Arrays.asList(descriptors));
 	}
 
+	/**
+	 * Returns a new {@code Snippet} that will document the links in the API operation's
+	 * response. Links will be extracted from the response using the given
+	 * {@code linkExtractor} and will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a link is present in the response, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a link
+	 * is documented, is not marked as optional, and is not present in the response, a
+	 * failure will also occur.
+	 * <p>
+	 * If you do not want to document a link, a link descriptor can be marked as
+	 * {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
+	 * generated snippet while avoiding the failure described above.
+	 * <p>
+	 * If a descriptor does not have a {@link LinkDescriptor#description(Object)
+	 * description}, the {@link Link#getTitle() title} of the link will be used. If the
+	 * link does not have a title a failure will occur.
+	 *
+	 * @param linkExtractor used to extract the links from the response
+	 * @param descriptors the descriptions of the response's links
+	 * @return the snippet that will document the links
+	 */
+	public static LinksSnippet links(LinkExtractor linkExtractor,
+			List<LinkDescriptor> descriptors) {
+		return new LinksSnippet(linkExtractor, descriptors);
+	}
+
 	/**
 	 * Returns a new {@code Snippet} that will document the links in the API operation's
 	 * response. Links will be extracted from the response using the given
@@ -186,6 +308,27 @@ public abstract class HypermediaDocumentation {
 		return new LinksSnippet(linkExtractor, Arrays.asList(descriptors), true);
 	}
 
+	/**
+	 * Returns a new {@code Snippet} that will document the links in the API operation's
+	 * response. Links will be extracted from the response using the given
+	 * {@code linkExtractor} and will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a link is documented, is not marked as optional, and is not present in the
+	 * response, a failure will occur. Any undocumented links will be ignored.
+	 * <p>
+	 * If a descriptor does not have a {@link LinkDescriptor#description(Object)
+	 * description}, the {@link Link#getTitle() title} of the link will be used. If the
+	 * link does not have a title a failure will occur.
+	 *
+	 * @param linkExtractor used to extract the links from the response
+	 * @param descriptors the descriptions of the response's links
+	 * @return the snippet that will document the links
+	 */
+	public static LinksSnippet relaxedLinks(LinkExtractor linkExtractor,
+											List<LinkDescriptor> descriptors) {
+		return new LinksSnippet(linkExtractor, descriptors, true);
+	}
+
 	/**
 	 * Returns a new {@code Snippet} that will document the links in the API operation's
 	 * response. The given {@code attributes} will be available during snippet generation.
@@ -215,6 +358,35 @@ public abstract class HypermediaDocumentation {
 		return new LinksSnippet(linkExtractor, Arrays.asList(descriptors), attributes);
 	}
 
+	/**
+	 * Returns a new {@code Snippet} that will document the links in the API operation's
+	 * response. The given {@code attributes} will be available during snippet generation.
+	 * Links will be extracted from the response using the given {@code linkExtractor} and
+	 * will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a link is present in the response, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a link
+	 * is documented, is not marked as optional, and is not present in the response, a
+	 * failure will also occur.
+	 * <p>
+	 * If you do not want to document a link, a link descriptor can be marked as
+	 * {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
+	 * generated snippet while avoiding the failure described above.
+	 * <p>
+	 * If a descriptor does not have a {@link LinkDescriptor#description(Object)
+	 * description}, the {@link Link#getTitle() title} of the link will be used. If the
+	 * link does not have a title a failure will occur.
+	 *
+	 * @param attributes the attributes
+	 * @param linkExtractor used to extract the links from the response
+	 * @param descriptors the descriptions of the response's links
+	 * @return the snippet that will document the links
+	 */
+	public static LinksSnippet links(LinkExtractor linkExtractor,
+			Map<String, Object> attributes, List<LinkDescriptor> descriptors) {
+		return new LinksSnippet(linkExtractor, descriptors, attributes);
+	}
+
 	/**
 	 * Returns a new {@code Snippet} that will document the links in the API operation's
 	 * response. The given {@code attributes} will be available during snippet generation.
@@ -239,6 +411,29 @@ public abstract class HypermediaDocumentation {
 				true);
 	}
 
+	/**
+	 * Returns a new {@code Snippet} that will document the links in the API operation's
+	 * response. The given {@code attributes} will be available during snippet generation.
+	 * Links will be extracted from the response using the given {@code linkExtractor} and
+	 * will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a link is documented, is not marked as optional, and is not present in the
+	 * response, a failure will occur. Any undocumented links will be ignored.
+	 * <p>
+	 * If a descriptor does not have a {@link LinkDescriptor#description(Object)
+	 * description}, the {@link Link#getTitle() title} of the link will be used. If the
+	 * link does not have a title a failure will occur.
+	 *
+	 * @param attributes the attributes
+	 * @param linkExtractor used to extract the links from the response
+	 * @param descriptors the descriptions of the response's links
+	 * @return the snippet that will document the links
+	 */
+	public static LinksSnippet relaxedLinks(LinkExtractor linkExtractor,
+											Map<String, Object> attributes, List<LinkDescriptor> descriptors) {
+		return new LinksSnippet(linkExtractor, descriptors, attributes, true);
+	}
+
 	/**
 	 * Returns a {@code LinkExtractor} capable of extracting links in Hypermedia
 	 * Application Language (HAL) format where the links are found in a map named
diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/PayloadDocumentation.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/PayloadDocumentation.java
index bfce1879..464b7e2f 100644
--- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/PayloadDocumentation.java
+++ b/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/PayloadDocumentation.java
@@ -121,6 +121,29 @@ public abstract class PayloadDocumentation {
 		return new RequestFieldsSnippet(Arrays.asList(descriptors));
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the fields of the API operations's
+	 * request payload. The fields will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a field is present in the request payload, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+	 * field is documented, is not marked as optional, and is not present in the request,
+	 * a failure will also occur. For payloads with a hierarchical structure, documenting
+	 * a field is sufficient for all of its descendants to also be treated as having been
+	 * documented.
+	 * <p>
+	 * If you do not want to document a field, a field descriptor can be marked as
+	 * {@link FieldDescriptor#ignored}. This will prevent it from appearing in the
+	 * generated snippet while avoiding the failure described above.
+	 *
+	 * @param descriptors the descriptions of the request payload's fields
+	 * @return the snippet that will document the fields
+	 * @see #fieldWithPath(String)
+	 */
+	public static RequestFieldsSnippet requestFields(List<FieldDescriptor> descriptors) {
+		return new RequestFieldsSnippet(descriptors);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the fields of the API operations's
 	 * request payload. The fields will be documented using the given {@code descriptors}.
@@ -137,6 +160,22 @@ public abstract class PayloadDocumentation {
 		return new RequestFieldsSnippet(Arrays.asList(descriptors), true);
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the fields of the API operations's
+	 * request payload. The fields will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a field is documented, is not marked as optional, and is not present in the
+	 * request, a failure will occur. Any undocumented fields will be ignored.
+	 *
+	 * @param descriptors the descriptions of the request payload's fields
+	 * @return the snippet that will document the fields
+	 * @see #fieldWithPath(String)
+	 */
+	public static RequestFieldsSnippet relaxedRequestFields(
+			List<FieldDescriptor> descriptors) {
+		return new RequestFieldsSnippet(descriptors, true);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the fields of the API operation's
 	 * request payload. The fields will be documented using the given {@code descriptors}
@@ -163,6 +202,32 @@ public abstract class PayloadDocumentation {
 		return new RequestFieldsSnippet(Arrays.asList(descriptors), attributes);
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the fields of the API operation's
+	 * request payload. The fields will be documented using the given {@code descriptors}
+	 * and the given {@code attributes} will be available during snippet generation.
+	 * <p>
+	 * If a field is present in the request payload, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+	 * field is documented, is not marked as optional, and is not present in the request
+	 * payload, a failure will also occur. For payloads with a hierarchical structure,
+	 * documenting a field is sufficient for all of its descendants to also be treated as
+	 * having been documented.
+	 * <p>
+	 * If you do not want to document a field, a field descriptor can be marked as
+	 * {@link FieldDescriptor#ignored}. This will prevent it from appearing in the
+	 * generated snippet while avoiding the failure described above.
+	 *
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the request payload's fields
+	 * @return the snippet that will document the fields
+	 * @see #fieldWithPath(String)
+	 */
+	public static RequestFieldsSnippet requestFields(Map<String, Object> attributes,
+			List<FieldDescriptor> descriptors) {
+		return new RequestFieldsSnippet(descriptors, attributes);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the fields of the API operation's
 	 * request payload. The fields will be documented using the given {@code descriptors}
@@ -181,6 +246,24 @@ public abstract class PayloadDocumentation {
 		return new RequestFieldsSnippet(Arrays.asList(descriptors), attributes, true);
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the fields of the API operation's
+	 * request payload. The fields will be documented using the given {@code descriptors}
+	 * and the given {@code attributes} will be available during snippet generation.
+	 * <p>
+	 * If a field is documented, is not marked as optional, and is not present in the
+	 * request, a failure will occur. Any undocumented fields will be ignored.
+	 *
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the request payload's fields
+	 * @return the snippet that will document the fields
+	 * @see #fieldWithPath(String)
+	 */
+	public static RequestFieldsSnippet relaxedRequestFields(
+			Map<String, Object> attributes, List<FieldDescriptor> descriptors) {
+		return new RequestFieldsSnippet(descriptors, attributes, true);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the fields of the API operation's
 	 * response payload. The fields will be documented using the given {@code descriptors}
@@ -205,6 +288,30 @@ public abstract class PayloadDocumentation {
 		return new ResponseFieldsSnippet(Arrays.asList(descriptors));
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the fields of the API operation's
+	 * response payload. The fields will be documented using the given {@code descriptors}
+	 * .
+	 * <p>
+	 * If a field is present in the response payload, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+	 * field is documented, is not marked as optional, and is not present in the response
+	 * payload, a failure will also occur. For payloads with a hierarchical structure,
+	 * documenting a field is sufficient for all of its descendants to also be treated as
+	 * having been documented.
+	 * <p>
+	 * If you do not want to document a field, a field descriptor can be marked as
+	 * {@link FieldDescriptor#ignored}. This will prevent it from appearing in the
+	 * generated snippet while avoiding the failure described above.
+	 *
+	 * @param descriptors the descriptions of the response payload's fields
+	 * @return the snippet that will document the fields
+	 * @see #fieldWithPath(String)
+	 */
+	public static ResponseFieldsSnippet responseFields(List<FieldDescriptor> descriptors) {
+		return new ResponseFieldsSnippet(descriptors);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the fields of the API operation's
 	 * response payload. The fields will be documented using the given {@code descriptors}
@@ -222,6 +329,23 @@ public abstract class PayloadDocumentation {
 		return new ResponseFieldsSnippet(Arrays.asList(descriptors), true);
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the fields of the API operation's
+	 * response payload. The fields will be documented using the given {@code descriptors}
+	 * .
+	 * <p>
+	 * If a field is documented, is not marked as optional, and is not present in the
+	 * request, a failure will occur. Any undocumented fields will be ignored.
+	 *
+	 * @param descriptors the descriptions of the response payload's fields
+	 * @return the snippet that will document the fields
+	 * @see #fieldWithPath(String)
+	 */
+	public static ResponseFieldsSnippet relaxedResponseFields(
+			List<FieldDescriptor> descriptors) {
+		return new ResponseFieldsSnippet(descriptors, true);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the fields of the API operation's
 	 * response payload. The fields will be documented using the given {@code descriptors}
@@ -248,6 +372,32 @@ public abstract class PayloadDocumentation {
 		return new ResponseFieldsSnippet(Arrays.asList(descriptors), attributes);
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the fields of the API operation's
+	 * response payload. The fields will be documented using the given {@code descriptors}
+	 * and the given {@code attributes} will be available during snippet generation.
+	 * <p>
+	 * If a field is present in the response payload, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+	 * field is documented, is not marked as optional, and is not present in the response
+	 * payload, a failure will also occur. For payloads with a hierarchical structure,
+	 * documenting a field is sufficient for all of its descendants to also be treated as
+	 * having been documented.
+	 * <p>
+	 * If you do not want to document a field, a field descriptor can be marked as
+	 * {@link FieldDescriptor#ignored}. This will prevent it from appearing in the
+	 * generated snippet while avoiding the failure described above.
+	 *
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the response payload's fields
+	 * @return the snippet that will document the fields
+	 * @see #fieldWithPath(String)
+	 */
+	public static ResponseFieldsSnippet responseFields(Map<String, Object> attributes,
+			List<FieldDescriptor> descriptors) {
+		return new ResponseFieldsSnippet(descriptors, attributes);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the fields of the API operation's
 	 * response payload. The fields will be documented using the given {@code descriptors}
@@ -266,6 +416,23 @@ public abstract class PayloadDocumentation {
 		return new ResponseFieldsSnippet(Arrays.asList(descriptors), attributes, true);
 	}
 
+	/** Returns a {@code Snippet} that will document the fields of the API operation's
+	 * response payload. The fields will be documented using the given {@code descriptors}
+	 * and the given {@code attributes} will be available during snippet generation.
+	 * <p>
+	 * If a field is documented, is not marked as optional, and is not present in the
+	 * request, a failure will occur. Any undocumented fields will be ignored.
+	 *
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the response payload's fields
+	 * @return the snippet that will document the fields
+	 * @see #fieldWithPath(String)
+	 */
+	public static ResponseFieldsSnippet relaxedResponseFields(
+			Map<String, Object> attributes, List<FieldDescriptor> descriptors) {
+		return new ResponseFieldsSnippet(descriptors, attributes, true);
+	}
+
 	/**
 	 * Creates a copy of the given {@code descriptors} with the given {@code pathPrefix}
 	 * applied to their paths.
diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestDocumentation.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestDocumentation.java
index 4fec764a..c343cd7c 100644
--- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestDocumentation.java
+++ b/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestDocumentation.java
@@ -17,6 +17,7 @@
 package org.springframework.restdocs.request;
 
 import java.util.Arrays;
+import java.util.List;
 import java.util.Map;
 
 import org.springframework.restdocs.operation.OperationRequest;
@@ -76,6 +77,28 @@ public abstract class RequestDocumentation {
 		return new PathParametersSnippet(Arrays.asList(descriptors));
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the path parameters from the API
+	 * operation's request. The parameters will be documented using the given
+	 * {@code descriptors}.
+	 * <p>
+	 * If a parameter is present in the request path, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+	 * parameter is documented, is not marked as optional, and is not present in the
+	 * request path, a failure will also occur.
+	 * <p>
+	 * If you do not want to document a path parameter, a parameter descriptor can be
+	 * marked as {@link ParameterDescriptor#ignored}. This will prevent it from appearing
+	 * in the generated snippet while avoiding the failure described above.
+	 *
+	 * @param descriptors the descriptions of the parameters in the request's path
+	 * @return the snippet that will document the parameters
+	 */
+	public static PathParametersSnippet pathParameters(
+			List<ParameterDescriptor> descriptors) {
+		return new PathParametersSnippet(descriptors);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the path parameters from the API
 	 * operation's request. The parameters will be documented using the given
@@ -92,6 +115,22 @@ public abstract class RequestDocumentation {
 		return new PathParametersSnippet(Arrays.asList(descriptors), true);
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the path parameters from the API
+	 * operation's request. The parameters will be documented using the given
+	 * {@code descriptors}.
+	 * <p>
+	 * If a parameter is documented, is not marked as optional, and is not present in the
+	 * response, a failure will occur. Any undocumented parameters will be ignored.
+	 *
+	 * @param descriptors the descriptions of the parameters in the request's path
+	 * @return the snippet that will document the parameters
+	 */
+	public static PathParametersSnippet relaxedPathParameters(
+			List<ParameterDescriptor> descriptors) {
+		return new PathParametersSnippet(descriptors, true);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the path parameters from the API
 	 * operation's request. The given {@code attributes} will be available during snippet
@@ -116,6 +155,30 @@ public abstract class RequestDocumentation {
 		return new PathParametersSnippet(Arrays.asList(descriptors), attributes);
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the path parameters from the API
+	 * operation's request. The given {@code attributes} will be available during snippet
+	 * rendering and the parameters will be documented using the given {@code descriptors}
+	 * .
+	 * <p>
+	 * If a parameter is present in the request path, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+	 * parameter is documented, is not marked as optional, and is not present in the
+	 * request path, a failure will also occur.
+	 * <p>
+	 * If you do not want to document a path parameter, a parameter descriptor can be
+	 * marked as {@link ParameterDescriptor#ignored}. This will prevent it from appearing
+	 * in the generated snippet while avoiding the failure described above.
+	 *
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the parameters in the request's path
+	 * @return the snippet that will document the parameters
+	 */
+	public static PathParametersSnippet pathParameters(Map<String, Object> attributes,
+			List<ParameterDescriptor> descriptors) {
+		return new PathParametersSnippet(descriptors, attributes);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the path parameters from the API
 	 * operation's request. The given {@code attributes} will be available during snippet
@@ -134,6 +197,24 @@ public abstract class RequestDocumentation {
 		return new PathParametersSnippet(Arrays.asList(descriptors), attributes, true);
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the path parameters from the API
+	 * operation's request. The given {@code attributes} will be available during snippet
+	 * rendering and the parameters will be documented using the given {@code descriptors}
+	 * .
+	 * <p>
+	 * If a parameter is documented, is not marked as optional, and is not present in the
+	 * response, a failure will occur. Any undocumented parameters will be ignored.
+	 *
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the parameters in the request's path
+	 * @return the snippet that will document the parameters
+	 */
+	public static PathParametersSnippet relaxedPathParameters(
+			Map<String, Object> attributes, List<ParameterDescriptor> descriptors) {
+		return new PathParametersSnippet(descriptors, attributes, true);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the parameters from the API
 	 * operation's request. The parameters will be documented using the given
@@ -157,6 +238,29 @@ public abstract class RequestDocumentation {
 		return new RequestParametersSnippet(Arrays.asList(descriptors));
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the parameters from the API
+	 * operation's request. The parameters will be documented using the given
+	 * {@code descriptors}.
+	 * <p>
+	 * If a parameter is present in the request, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+	 * parameter is documented, is not marked as optional, and is not present in the
+	 * request, a failure will also occur.
+	 * <p>
+	 * If you do not want to document a request parameter, a parameter descriptor can be
+	 * marked as {@link ParameterDescriptor#ignored}. This will prevent it from appearing
+	 * in the generated snippet while avoiding the failure described above.
+	 *
+	 * @param descriptors The descriptions of the request's parameters
+	 * @return the snippet
+	 * @see OperationRequest#getParameters()
+	 */
+	public static RequestParametersSnippet requestParameters(
+			List<ParameterDescriptor> descriptors) {
+		return new RequestParametersSnippet(descriptors);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the parameters from the API
 	 * operation's request. The parameters will be documented using the given
@@ -174,6 +278,23 @@ public abstract class RequestDocumentation {
 		return new RequestParametersSnippet(Arrays.asList(descriptors), true);
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the parameters from the API
+	 * operation's request. The parameters will be documented using the given
+	 * {@code descriptors}.
+	 * <p>
+	 * If a parameter is documented, is not marked as optional, and is not present in the
+	 * response, a failure will occur. Any undocumented parameters will be ignored.
+	 *
+	 * @param descriptors The descriptions of the request's parameters
+	 * @return the snippet
+	 * @see OperationRequest#getParameters()
+	 */
+	public static RequestParametersSnippet relaxedRequestParameters(
+			List<ParameterDescriptor> descriptors) {
+		return new RequestParametersSnippet(descriptors, true);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the parameters from the API
 	 * operation's request. The given {@code attributes} will be available during snippet
@@ -199,6 +320,31 @@ public abstract class RequestDocumentation {
 		return new RequestParametersSnippet(Arrays.asList(descriptors), attributes);
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the parameters from the API
+	 * operation's request. The given {@code attributes} will be available during snippet
+	 * rendering and the parameters will be documented using the given {@code descriptors}
+	 * .
+	 * <p>
+	 * If a parameter is present in the request, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+	 * parameter is documented, is not marked as optional, and is not present in the
+	 * request, a failure will also occur.
+	 * <p>
+	 * If you do not want to document a request parameter, a parameter descriptor can be
+	 * marked as {@link ParameterDescriptor#ignored}. This will prevent it from appearing
+	 * in the generated snippet while avoiding the failure described above.
+	 *
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the request's parameters
+	 * @return the snippet that will document the parameters
+	 * @see OperationRequest#getParameters()
+	 */
+	public static RequestParametersSnippet requestParameters(
+			Map<String, Object> attributes, List<ParameterDescriptor> descriptors) {
+		return new RequestParametersSnippet(descriptors, attributes);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the parameters from the API
 	 * operation's request. The given {@code attributes} will be available during snippet
@@ -218,6 +364,25 @@ public abstract class RequestDocumentation {
 		return new RequestParametersSnippet(Arrays.asList(descriptors), attributes, true);
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the parameters from the API
+	 * operation's request. The given {@code attributes} will be available during snippet
+	 * rendering and the parameters will be documented using the given {@code descriptors}
+	 * .
+	 * <p>
+	 * If a parameter is documented, is not marked as optional, and is not present in the
+	 * response, a failure will occur. Any undocumented parameters will be ignored.
+	 *
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the request's parameters
+	 * @return the snippet that will document the parameters
+	 * @see OperationRequest#getParameters()
+	 */
+	public static RequestParametersSnippet relaxedRequestParameters(
+			Map<String, Object> attributes, List<ParameterDescriptor> descriptors) {
+		return new RequestParametersSnippet(descriptors, attributes, true);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the parts from the API operation's
 	 * request. The parts will be documented using the given {@code descriptors}.
@@ -239,6 +404,27 @@ public abstract class RequestDocumentation {
 		return new RequestPartsSnippet(Arrays.asList(descriptors));
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the parts from the API operation's
+	 * request. The parts will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a part is present in the request, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a part
+	 * is documented, is not marked as optional, and is not present in the request, a
+	 * failure will also occur.
+	 * <p>
+	 * If you do not want to document a part, a part descriptor can be marked as
+	 * {@link RequestPartDescriptor#ignored}. This will prevent it from appearing in the
+	 * generated snippet while avoiding the failure described above.
+	 *
+	 * @param descriptors The descriptions of the request's parts
+	 * @return the snippet
+	 * @see OperationRequest#getParts()
+	 */
+	public static RequestPartsSnippet requestParts(List<RequestPartDescriptor> descriptors) {
+		return new RequestPartsSnippet(descriptors);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the parts from the API operation's
 	 * request. The parameters will be documented using the given {@code descriptors}.
@@ -255,6 +441,22 @@ public abstract class RequestDocumentation {
 		return new RequestPartsSnippet(Arrays.asList(descriptors), true);
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the parts from the API operation's
+	 * request. The parameters will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a part is documented, is not marked as optional, and is not present in the
+	 * request, a failure will occur. Any undocumented parts will be ignored.
+	 *
+	 * @param descriptors The descriptions of the request's parts
+	 * @return the snippet
+	 * @see OperationRequest#getParts()
+	 */
+	public static RequestPartsSnippet relaxedRequestParts(
+			List<RequestPartDescriptor> descriptors) {
+		return new RequestPartsSnippet(descriptors, true);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the parts from the API operation's
 	 * request. The given {@code attributes} will be available during snippet rendering
@@ -279,6 +481,30 @@ public abstract class RequestDocumentation {
 		return new RequestPartsSnippet(Arrays.asList(descriptors), attributes);
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the parts from the API operation's
+	 * request. The given {@code attributes} will be available during snippet rendering
+	 * and the parts will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a part is present in the request, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a part
+	 * is documented, is not marked as optional, and is not present in the request, a
+	 * failure will also occur.
+	 * <p>
+	 * If you do not want to document a part, a part descriptor can be marked as
+	 * {@link RequestPartDescriptor#ignored}. This will prevent it from appearing in the
+	 * generated snippet while avoiding the failure described above.
+	 *
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the request's parts
+	 * @return the snippet
+	 * @see OperationRequest#getParts()
+	 */
+	public static RequestPartsSnippet requestParts(Map<String, Object> attributes,
+			List<RequestPartDescriptor> descriptors) {
+		return new RequestPartsSnippet(descriptors, attributes);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the parts from the API operation's
 	 * request. The given {@code attributes} will be available during snippet rendering
@@ -297,4 +523,22 @@ public abstract class RequestDocumentation {
 		return new RequestPartsSnippet(Arrays.asList(descriptors), attributes, true);
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the parts from the API operation's
+	 * request. The given {@code attributes} will be available during snippet rendering
+	 * and the parts will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a part is documented, is not marked as optional, and is not present in the
+	 * request, a failure will occur. Any undocumented parts will be ignored.
+	 *
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the request's parts
+	 * @return the snippet
+	 * @see OperationRequest#getParameters()
+	 */
+	public static RequestPartsSnippet relaxedRequestParts(Map<String, Object> attributes,
+			List<RequestPartDescriptor> descriptors) {
+		return new RequestPartsSnippet(descriptors, attributes, true);
+	}
+
 }

From 81b2f11ebfa223cdb2b27dd1ea39cabdbecd9a1a Mon Sep 17 00:00:00 2001
From: Andy Wilkinson <awilkinson@pivotal.io>
Date: Tue, 24 May 2016 13:54:17 +0100
Subject: [PATCH 2/2] Polish "Allow descriptors to be provided as a List as
 well as via varags"

See gh-247
---
 .../restdocs/headers/HeaderDocumentation.java | 12 ++++---
 .../hypermedia/HypermediaDocumentation.java   | 31 +++++++++----------
 .../payload/PayloadDocumentation.java         | 27 +++++++++-------
 .../request/RequestDocumentation.java         | 28 +++++++++--------
 4 files changed, 51 insertions(+), 47 deletions(-)

diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/HeaderDocumentation.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/HeaderDocumentation.java
index 740f6a78..9f32638e 100644
--- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/HeaderDocumentation.java
+++ b/spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/HeaderDocumentation.java
@@ -27,6 +27,7 @@ import org.springframework.restdocs.snippet.Snippet;
  *
  * @author Andreas Evers
  * @author Andy Wilkinson
+ * @author Marcel Overdijk
  */
 public abstract class HeaderDocumentation {
 
@@ -57,7 +58,7 @@ public abstract class HeaderDocumentation {
 	 * @see #headerWithName(String)
 	 */
 	public static RequestHeadersSnippet requestHeaders(HeaderDescriptor... descriptors) {
-		return new RequestHeadersSnippet(Arrays.asList(descriptors));
+		return requestHeaders(Arrays.asList(descriptors));
 	}
 
 	/**
@@ -71,7 +72,8 @@ public abstract class HeaderDocumentation {
 	 * @return the snippet that will document the request headers
 	 * @see #headerWithName(String)
 	 */
-	public static RequestHeadersSnippet requestHeaders(List<HeaderDescriptor> descriptors) {
+	public static RequestHeadersSnippet requestHeaders(
+			List<HeaderDescriptor> descriptors) {
 		return new RequestHeadersSnippet(descriptors);
 	}
 
@@ -90,7 +92,7 @@ public abstract class HeaderDocumentation {
 	 */
 	public static RequestHeadersSnippet requestHeaders(Map<String, Object> attributes,
 			HeaderDescriptor... descriptors) {
-		return new RequestHeadersSnippet(Arrays.asList(descriptors), attributes);
+		return requestHeaders(attributes, Arrays.asList(descriptors));
 	}
 
 	/**
@@ -124,7 +126,7 @@ public abstract class HeaderDocumentation {
 	 */
 	public static ResponseHeadersSnippet responseHeaders(
 			HeaderDescriptor... descriptors) {
-		return new ResponseHeadersSnippet(Arrays.asList(descriptors));
+		return responseHeaders(Arrays.asList(descriptors));
 	}
 
 	/**
@@ -159,7 +161,7 @@ public abstract class HeaderDocumentation {
 	 */
 	public static ResponseHeadersSnippet responseHeaders(Map<String, Object> attributes,
 			HeaderDescriptor... descriptors) {
-		return new ResponseHeadersSnippet(Arrays.asList(descriptors), attributes);
+		return responseHeaders(attributes, Arrays.asList(descriptors));
 	}
 
 	/**
diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/HypermediaDocumentation.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/HypermediaDocumentation.java
index a6098ce5..191ffea3 100644
--- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/HypermediaDocumentation.java
+++ b/spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/HypermediaDocumentation.java
@@ -24,6 +24,7 @@ import java.util.Map;
  * Static factory methods for documenting a RESTful API that utilizes Hypermedia.
  *
  * @author Andy Wilkinson
+ * @author Marcel Overdijk
  */
 public abstract class HypermediaDocumentation {
 
@@ -63,8 +64,7 @@ public abstract class HypermediaDocumentation {
 	 * @return the snippet that will document the links
 	 */
 	public static LinksSnippet links(LinkDescriptor... descriptors) {
-		return new LinksSnippet(new ContentTypeLinkExtractor(),
-				Arrays.asList(descriptors));
+		return links(Arrays.asList(descriptors));
 	}
 
 	/**
@@ -108,8 +108,7 @@ public abstract class HypermediaDocumentation {
 	 * @return the snippet that will document the links
 	 */
 	public static LinksSnippet relaxedLinks(LinkDescriptor... descriptors) {
-		return new LinksSnippet(new ContentTypeLinkExtractor(),
-				Arrays.asList(descriptors), true);
+		return relaxedLinks(Arrays.asList(descriptors));
 	}
 
 	/**
@@ -156,8 +155,7 @@ public abstract class HypermediaDocumentation {
 	 */
 	public static LinksSnippet links(Map<String, Object> attributes,
 			LinkDescriptor... descriptors) {
-		return new LinksSnippet(new ContentTypeLinkExtractor(),
-				Arrays.asList(descriptors), attributes);
+		return links(attributes, Arrays.asList(descriptors));
 	}
 
 	/**
@@ -207,8 +205,7 @@ public abstract class HypermediaDocumentation {
 	 */
 	public static LinksSnippet relaxedLinks(Map<String, Object> attributes,
 			LinkDescriptor... descriptors) {
-		return new LinksSnippet(new ContentTypeLinkExtractor(),
-				Arrays.asList(descriptors), attributes, true);
+		return relaxedLinks(attributes, Arrays.asList(descriptors));
 	}
 
 	/**
@@ -229,8 +226,9 @@ public abstract class HypermediaDocumentation {
 	 * @return the snippet that will document the links
 	 */
 	public static LinksSnippet relaxedLinks(Map<String, Object> attributes,
-											List<LinkDescriptor> descriptors) {
-		return new LinksSnippet(new ContentTypeLinkExtractor(), descriptors, attributes, true);
+			List<LinkDescriptor> descriptors) {
+		return new LinksSnippet(new ContentTypeLinkExtractor(), descriptors, attributes,
+				true);
 	}
 
 	/**
@@ -257,7 +255,7 @@ public abstract class HypermediaDocumentation {
 	 */
 	public static LinksSnippet links(LinkExtractor linkExtractor,
 			LinkDescriptor... descriptors) {
-		return new LinksSnippet(linkExtractor, Arrays.asList(descriptors));
+		return links(linkExtractor, Arrays.asList(descriptors));
 	}
 
 	/**
@@ -305,7 +303,7 @@ public abstract class HypermediaDocumentation {
 	 */
 	public static LinksSnippet relaxedLinks(LinkExtractor linkExtractor,
 			LinkDescriptor... descriptors) {
-		return new LinksSnippet(linkExtractor, Arrays.asList(descriptors), true);
+		return relaxedLinks(linkExtractor, Arrays.asList(descriptors));
 	}
 
 	/**
@@ -325,7 +323,7 @@ public abstract class HypermediaDocumentation {
 	 * @return the snippet that will document the links
 	 */
 	public static LinksSnippet relaxedLinks(LinkExtractor linkExtractor,
-											List<LinkDescriptor> descriptors) {
+			List<LinkDescriptor> descriptors) {
 		return new LinksSnippet(linkExtractor, descriptors, true);
 	}
 
@@ -355,7 +353,7 @@ public abstract class HypermediaDocumentation {
 	 */
 	public static LinksSnippet links(LinkExtractor linkExtractor,
 			Map<String, Object> attributes, LinkDescriptor... descriptors) {
-		return new LinksSnippet(linkExtractor, Arrays.asList(descriptors), attributes);
+		return links(linkExtractor, attributes, Arrays.asList(descriptors));
 	}
 
 	/**
@@ -407,8 +405,7 @@ public abstract class HypermediaDocumentation {
 	 */
 	public static LinksSnippet relaxedLinks(LinkExtractor linkExtractor,
 			Map<String, Object> attributes, LinkDescriptor... descriptors) {
-		return new LinksSnippet(linkExtractor, Arrays.asList(descriptors), attributes,
-				true);
+		return relaxedLinks(linkExtractor, attributes, Arrays.asList(descriptors));
 	}
 
 	/**
@@ -430,7 +427,7 @@ public abstract class HypermediaDocumentation {
 	 * @return the snippet that will document the links
 	 */
 	public static LinksSnippet relaxedLinks(LinkExtractor linkExtractor,
-											Map<String, Object> attributes, List<LinkDescriptor> descriptors) {
+			Map<String, Object> attributes, List<LinkDescriptor> descriptors) {
 		return new LinksSnippet(linkExtractor, descriptors, attributes, true);
 	}
 
diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/PayloadDocumentation.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/PayloadDocumentation.java
index 464b7e2f..9a552c92 100644
--- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/PayloadDocumentation.java
+++ b/spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/PayloadDocumentation.java
@@ -26,6 +26,7 @@ import java.util.Map;
  *
  * @author Andreas Evers
  * @author Andy Wilkinson
+ * @author Marcel Overdijk
  */
 public abstract class PayloadDocumentation {
 
@@ -118,7 +119,7 @@ public abstract class PayloadDocumentation {
 	 * @see #fieldWithPath(String)
 	 */
 	public static RequestFieldsSnippet requestFields(FieldDescriptor... descriptors) {
-		return new RequestFieldsSnippet(Arrays.asList(descriptors));
+		return requestFields(Arrays.asList(descriptors));
 	}
 
 	/**
@@ -157,7 +158,7 @@ public abstract class PayloadDocumentation {
 	 */
 	public static RequestFieldsSnippet relaxedRequestFields(
 			FieldDescriptor... descriptors) {
-		return new RequestFieldsSnippet(Arrays.asList(descriptors), true);
+		return relaxedRequestFields(Arrays.asList(descriptors));
 	}
 
 	/**
@@ -199,7 +200,7 @@ public abstract class PayloadDocumentation {
 	 */
 	public static RequestFieldsSnippet requestFields(Map<String, Object> attributes,
 			FieldDescriptor... descriptors) {
-		return new RequestFieldsSnippet(Arrays.asList(descriptors), attributes);
+		return requestFields(attributes, Arrays.asList(descriptors));
 	}
 
 	/**
@@ -243,7 +244,7 @@ public abstract class PayloadDocumentation {
 	 */
 	public static RequestFieldsSnippet relaxedRequestFields(
 			Map<String, Object> attributes, FieldDescriptor... descriptors) {
-		return new RequestFieldsSnippet(Arrays.asList(descriptors), attributes, true);
+		return relaxedRequestFields(attributes, Arrays.asList(descriptors));
 	}
 
 	/**
@@ -285,7 +286,7 @@ public abstract class PayloadDocumentation {
 	 * @see #fieldWithPath(String)
 	 */
 	public static ResponseFieldsSnippet responseFields(FieldDescriptor... descriptors) {
-		return new ResponseFieldsSnippet(Arrays.asList(descriptors));
+		return responseFields(Arrays.asList(descriptors));
 	}
 
 	/**
@@ -308,7 +309,8 @@ public abstract class PayloadDocumentation {
 	 * @return the snippet that will document the fields
 	 * @see #fieldWithPath(String)
 	 */
-	public static ResponseFieldsSnippet responseFields(List<FieldDescriptor> descriptors) {
+	public static ResponseFieldsSnippet responseFields(
+			List<FieldDescriptor> descriptors) {
 		return new ResponseFieldsSnippet(descriptors);
 	}
 
@@ -326,7 +328,7 @@ public abstract class PayloadDocumentation {
 	 */
 	public static ResponseFieldsSnippet relaxedResponseFields(
 			FieldDescriptor... descriptors) {
-		return new ResponseFieldsSnippet(Arrays.asList(descriptors), true);
+		return relaxedResponseFields(Arrays.asList(descriptors));
 	}
 
 	/**
@@ -369,7 +371,7 @@ public abstract class PayloadDocumentation {
 	 */
 	public static ResponseFieldsSnippet responseFields(Map<String, Object> attributes,
 			FieldDescriptor... descriptors) {
-		return new ResponseFieldsSnippet(Arrays.asList(descriptors), attributes);
+		return responseFields(attributes, Arrays.asList(descriptors));
 	}
 
 	/**
@@ -413,10 +415,11 @@ public abstract class PayloadDocumentation {
 	 */
 	public static ResponseFieldsSnippet relaxedResponseFields(
 			Map<String, Object> attributes, FieldDescriptor... descriptors) {
-		return new ResponseFieldsSnippet(Arrays.asList(descriptors), attributes, true);
+		return relaxedResponseFields(attributes, Arrays.asList(descriptors));
 	}
 
-	/** Returns a {@code Snippet} that will document the fields of the API operation's
+	/**
+	 * Returns a {@code Snippet} that will document the fields of the API operation's
 	 * response payload. The fields will be documented using the given {@code descriptors}
 	 * and the given {@code attributes} will be available during snippet generation.
 	 * <p>
@@ -447,8 +450,8 @@ public abstract class PayloadDocumentation {
 		for (FieldDescriptor descriptor : descriptors) {
 			FieldDescriptor prefixedDescriptor = new FieldDescriptor(
 					pathPrefix + descriptor.getPath())
-					.description(descriptor.getDescription())
-					.type(descriptor.getType());
+							.description(descriptor.getDescription())
+							.type(descriptor.getType());
 			if (descriptor.isIgnored()) {
 				prefixedDescriptor.ignored();
 			}
diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestDocumentation.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestDocumentation.java
index c343cd7c..043fdfe6 100644
--- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestDocumentation.java
+++ b/spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestDocumentation.java
@@ -26,6 +26,7 @@ import org.springframework.restdocs.operation.OperationRequest;
  * Static factory methods for documenting aspects of a request sent to a RESTful API.
  *
  * @author Andy Wilkinson
+ * @author Marcel Overdijk
  */
 public abstract class RequestDocumentation {
 
@@ -74,7 +75,7 @@ public abstract class RequestDocumentation {
 	 */
 	public static PathParametersSnippet pathParameters(
 			ParameterDescriptor... descriptors) {
-		return new PathParametersSnippet(Arrays.asList(descriptors));
+		return pathParameters(Arrays.asList(descriptors));
 	}
 
 	/**
@@ -112,7 +113,7 @@ public abstract class RequestDocumentation {
 	 */
 	public static PathParametersSnippet relaxedPathParameters(
 			ParameterDescriptor... descriptors) {
-		return new PathParametersSnippet(Arrays.asList(descriptors), true);
+		return relaxedPathParameters(Arrays.asList(descriptors));
 	}
 
 	/**
@@ -152,7 +153,7 @@ public abstract class RequestDocumentation {
 	 */
 	public static PathParametersSnippet pathParameters(Map<String, Object> attributes,
 			ParameterDescriptor... descriptors) {
-		return new PathParametersSnippet(Arrays.asList(descriptors), attributes);
+		return pathParameters(attributes, Arrays.asList(descriptors));
 	}
 
 	/**
@@ -194,7 +195,7 @@ public abstract class RequestDocumentation {
 	 */
 	public static PathParametersSnippet relaxedPathParameters(
 			Map<String, Object> attributes, ParameterDescriptor... descriptors) {
-		return new PathParametersSnippet(Arrays.asList(descriptors), attributes, true);
+		return relaxedPathParameters(attributes, Arrays.asList(descriptors));
 	}
 
 	/**
@@ -235,7 +236,7 @@ public abstract class RequestDocumentation {
 	 */
 	public static RequestParametersSnippet requestParameters(
 			ParameterDescriptor... descriptors) {
-		return new RequestParametersSnippet(Arrays.asList(descriptors));
+		return requestParameters(Arrays.asList(descriptors));
 	}
 
 	/**
@@ -275,7 +276,7 @@ public abstract class RequestDocumentation {
 	 */
 	public static RequestParametersSnippet relaxedRequestParameters(
 			ParameterDescriptor... descriptors) {
-		return new RequestParametersSnippet(Arrays.asList(descriptors), true);
+		return relaxedRequestParameters(Arrays.asList(descriptors));
 	}
 
 	/**
@@ -317,7 +318,7 @@ public abstract class RequestDocumentation {
 	 */
 	public static RequestParametersSnippet requestParameters(
 			Map<String, Object> attributes, ParameterDescriptor... descriptors) {
-		return new RequestParametersSnippet(Arrays.asList(descriptors), attributes);
+		return requestParameters(attributes, Arrays.asList(descriptors));
 	}
 
 	/**
@@ -361,7 +362,7 @@ public abstract class RequestDocumentation {
 	 */
 	public static RequestParametersSnippet relaxedRequestParameters(
 			Map<String, Object> attributes, ParameterDescriptor... descriptors) {
-		return new RequestParametersSnippet(Arrays.asList(descriptors), attributes, true);
+		return relaxedRequestParameters(attributes, Arrays.asList(descriptors));
 	}
 
 	/**
@@ -401,7 +402,7 @@ public abstract class RequestDocumentation {
 	 * @see OperationRequest#getParts()
 	 */
 	public static RequestPartsSnippet requestParts(RequestPartDescriptor... descriptors) {
-		return new RequestPartsSnippet(Arrays.asList(descriptors));
+		return requestParts(Arrays.asList(descriptors));
 	}
 
 	/**
@@ -421,7 +422,8 @@ public abstract class RequestDocumentation {
 	 * @return the snippet
 	 * @see OperationRequest#getParts()
 	 */
-	public static RequestPartsSnippet requestParts(List<RequestPartDescriptor> descriptors) {
+	public static RequestPartsSnippet requestParts(
+			List<RequestPartDescriptor> descriptors) {
 		return new RequestPartsSnippet(descriptors);
 	}
 
@@ -438,7 +440,7 @@ public abstract class RequestDocumentation {
 	 */
 	public static RequestPartsSnippet relaxedRequestParts(
 			RequestPartDescriptor... descriptors) {
-		return new RequestPartsSnippet(Arrays.asList(descriptors), true);
+		return relaxedRequestParts(Arrays.asList(descriptors));
 	}
 
 	/**
@@ -478,7 +480,7 @@ public abstract class RequestDocumentation {
 	 */
 	public static RequestPartsSnippet requestParts(Map<String, Object> attributes,
 			RequestPartDescriptor... descriptors) {
-		return new RequestPartsSnippet(Arrays.asList(descriptors), attributes);
+		return requestParts(attributes, Arrays.asList(descriptors));
 	}
 
 	/**
@@ -520,7 +522,7 @@ public abstract class RequestDocumentation {
 	 */
 	public static RequestPartsSnippet relaxedRequestParts(Map<String, Object> attributes,
 			RequestPartDescriptor... descriptors) {
-		return new RequestPartsSnippet(Arrays.asList(descriptors), attributes, true);
+		return relaxedRequestParts(attributes, Arrays.asList(descriptors));
 	}
 
 	/**