Introduce relaxed snippets that don’t fail when item is not documented

Previously, many of the snippets would fail when something wasn’t documented. This worked well when writing exhaustive API documentation, but was cumbersome when trying to document a scenario that might only being interested in a subset of the links, response fields, etc. It was necessary to mark things that were not of interest as being ignored. This commit introduces a relaxed variant of several snippets. A relaxed snippet will not fail if something has not been documented. Instead, the undocumented thing will be ignored. If something has been documented but it does not exist a failure will still occur. Closes gh-175

Author: wilkinsona

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

@@ -66,6 +66,26 @@ public static LinksSnippet links(LinkDescriptor... descriptors) {
 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 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(LinkDescriptor... descriptors) {
+return new LinksSnippet(new ContentTypeLinkExtractor(),
+Arrays.asList(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.
@@ -80,6 +100,10 @@ public static LinksSnippet links(LinkDescriptor... descriptors) {
  * 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
@@ -91,6 +115,29 @@ public static LinksSnippet links(Map<String, Object> attributes,
 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 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,
+LinkDescriptor... descriptors) {
+return new LinksSnippet(new ContentTypeLinkExtractor(),
+Arrays.asList(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
@@ -104,6 +151,10 @@ public static LinksSnippet links(Map<String, Object> attributes,
  * 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
@@ -114,6 +165,27 @@ public static LinksSnippet links(LinkExtractor linkExtractor,
 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 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,
+LinkDescriptor... descriptors) {
+return new LinksSnippet(linkExtractor, Arrays.asList(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.
@@ -128,6 +200,10 @@ public static LinksSnippet links(LinkExtractor linkExtractor,
  * 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
@@ -139,6 +215,30 @@ public static LinksSnippet links(LinkExtractor linkExtractor,
 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 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, LinkDescriptor... descriptors) {
+return new LinksSnippet(linkExtractor, Arrays.asList(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

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

@@ -19,6 +19,7 @@
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.LinkedHashMap;
@@ -50,35 +51,72 @@ public class LinksSnippet extends TemplatedSnippet {
 
 private final LinkExtractor linkExtractor;
 
+private final boolean ignoreUndocumentedLinks;
+
 /**
  * Creates a new {@code LinksSnippet} that will extract links using the given
  * {@code linkExtractor} and document them using the given {@code descriptors}.
+ * Undocumented links will trigger a failure.
  *
  * @param linkExtractor the link extractor
  * @param descriptors the link descriptors
  */
 protected LinksSnippet(LinkExtractor linkExtractor,
 List<LinkDescriptor> descriptors) {
-this(linkExtractor, descriptors, null);
+this(linkExtractor, descriptors, null, false);
+}
+
+/**
+ * Creates a new {@code LinksSnippet} that will extract links using the given
+ * {@code linkExtractor} and document them using the given {@code descriptors}. If
+ * {@code ignoreUndocumentedLinks} is {@code true}, undocumented links will be ignored
+ * and will not trigger a failure.
+ *
+ * @param linkExtractor the link extractor
+ * @param descriptors the link descriptors
+ * @param ignoreUndocumentedLinks whether undocumented links should be ignored
+ */
+protected LinksSnippet(LinkExtractor linkExtractor, List<LinkDescriptor> descriptors,
+boolean ignoreUndocumentedLinks) {
+this(linkExtractor, descriptors, null, ignoreUndocumentedLinks);
 }
 
 /**
  * Creates a new {@code LinksSnippet} that will extract links using the given
  * {@code linkExtractor} and document them using the given {@code descriptors}. The
  * given {@code attributes} will be included in the model during template rendering.
+ * Undocumented links will trigger a failure.
  *
  * @param linkExtractor the link extractor
  * @param descriptors the link descriptors
  * @param attributes the additional attributes
  */
 protected LinksSnippet(LinkExtractor linkExtractor, List<LinkDescriptor> descriptors,
 Map<String, Object> attributes) {
+this(linkExtractor, descriptors, attributes, false);
+}
+
+/**
+ * Creates a new {@code LinksSnippet} that will extract links using the given
+ * {@code linkExtractor} and document them using the given {@code descriptors}. The
+ * given {@code attributes} will be included in the model during template rendering.
+ * If {@code ignoreUndocumentedLinks} is {@code true}, undocumented links will be
+ * ignored and will not trigger a failure.
+ *
+ * @param linkExtractor the link extractor
+ * @param descriptors the link descriptors
+ * @param attributes the additional attributes
+ * @param ignoreUndocumentedLinks whether undocumented links should be ignored
+ */
+protected LinksSnippet(LinkExtractor linkExtractor, List<LinkDescriptor> descriptors,
+Map<String, Object> attributes, boolean ignoreUndocumentedLinks) {
 super("links", attributes);
 this.linkExtractor = linkExtractor;
 for (LinkDescriptor descriptor : descriptors) {
 Assert.notNull(descriptor.getRel(), "Link descriptors must have a rel");
 this.descriptorsByRel.put(descriptor.getRel(), descriptor);
 }
+this.ignoreUndocumentedLinks = ignoreUndocumentedLinks;
 }
 
 @Override
@@ -100,8 +138,14 @@ protected Map<String, Object> createModel(Operation operation) {
 private void validate(Map<String, List<Link>> links) {
 Set<String> actualRels = links.keySet();
 
-Set<String> undocumentedRels = new HashSet<>(actualRels);
-undocumentedRels.removeAll(this.descriptorsByRel.keySet());
+Set<String> undocumentedRels;
+if (this.ignoreUndocumentedLinks) {
+undocumentedRels = Collections.emptySet();
+}
+else {
+undocumentedRels = new HashSet<>(actualRels);
+undocumentedRels.removeAll(this.descriptorsByRel.keySet());
+}
 
 Set<String> requiredRels = new HashSet<>();
 for (Entry<String, LinkDescriptor> relAndDescriptor : this.descriptorsByRel

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

@@ -39,20 +39,42 @@
  */
 public abstract class AbstractFieldsSnippet extends TemplatedSnippet {
 
-private List<FieldDescriptor> fieldDescriptors;
+private final List<FieldDescriptor> fieldDescriptors;
+
+private final boolean ignoreUndocumentedFields;
 
 /**
  * Creates a new {@code AbstractFieldsSnippet} that will produce a snippet named
  * {@code <type>-fields}. The fields will be documented using the given
  * {@code descriptors} and the given {@code attributes} will be included in the model
- * during template rendering.
+ * during template rendering. Undocumented fields will trigger a failure.
  *
  * @param type the type of the fields
  * @param descriptors the field descriptors
  * @param attributes the additional attributes
+ * @deprecated since 1.1 in favor of
+ * {@link #AbstractFieldsSnippet(String, List, Map, boolean)}
  */
+@Deprecated
 protected AbstractFieldsSnippet(String type, List<FieldDescriptor> descriptors,
 Map<String, Object> attributes) {
+this(type, descriptors, attributes, false);
+}
+
+/**
+ * Creates a new {@code AbstractFieldsSnippet} that will produce a snippet named
+ * {@code <type>-fields}. The fields will be documented using the given
+ * {@code descriptors} and the given {@code attributes} will be included in the model
+ * during template rendering. If {@code ignoreUndocumentedFields} is {@code true},
+ * undocumented fields will be ignored and will not trigger a failure.
+ *
+ * @param type the type of the fields
+ * @param descriptors the field descriptors
+ * @param attributes the additional attributes
+ * @param ignoreUndocumentedFields whether undocumented fields should be ignored
+ */
+protected AbstractFieldsSnippet(String type, List<FieldDescriptor> descriptors,
+Map<String, Object> attributes, boolean ignoreUndocumentedFields) {
 super(type + "-fields", attributes);
 for (FieldDescriptor descriptor : descriptors) {
 Assert.notNull(descriptor.getPath(), "Field descriptors must have a path");
@@ -65,6 +87,7 @@ protected AbstractFieldsSnippet(String type, List<FieldDescriptor> descriptors,
 
 }
 this.fieldDescriptors = descriptors;
+this.ignoreUndocumentedFields = ignoreUndocumentedFields;
 }
 
 @Override
@@ -111,8 +134,9 @@ private ContentHandler getContentHandler(Operation operation) {
 private void validateFieldDocumentation(ContentHandler payloadHandler) {
 List<FieldDescriptor> missingFields = payloadHandler
 .findMissingFields(this.fieldDescriptors);
-String undocumentedPayload = payloadHandler
-.getUndocumentedContent(this.fieldDescriptors);
+
+String undocumentedPayload = this.ignoreUndocumentedFields ? null
+: payloadHandler.getUndocumentedContent(this.fieldDescriptors);
 
 if (!missingFields.isEmpty() || StringUtils.hasText(undocumentedPayload)) {
 String message = "";