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] 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);
+	}
+
 }