Derive a link's description from its title

Previously, a LinkDescriptor had to be created with both a rel and a description. If a description was not provided a failure would occur. This commit relaxes the above-described restriction by allowing a link's title to be used as its default description. If a descriptor has a description, it will always be used irrespective of whether or not the link has a title. If the descriptor does not have a description and the link does have a title, the link's title will be used. If the descriptor does not have a description and the link does not have a title a failure will occur. Closes gh-105

Author: wilkinsona

docs/src/docs/asciidoc/documenting-your-api.adoc

@@ -38,6 +38,10 @@ include::{examples-dir}/com/example/restassured/Hypermedia.java[tag=links]
 The result is a snippet named `links.adoc` that contains a table describing the resource's
 links.
 
+TIP: If a link in the response has a `title`, the description can be omitted from its
+descriptor and the `title` will be used. If you omit the description and the link does
+not have a `title` a failure will occur.
+
 When documenting links, the test will fail if an undocumented link is found in the
 response. Similarly, the test will also fail if a documented link is not found in the
 response and the link has not been marked as optional.

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

@@ -51,7 +51,9 @@ private static Link maybeCreateLink(Map<String, Object> linkMap) {
 Object hrefObject = linkMap.get("href");
 Object relObject = linkMap.get("rel");
 if (relObject instanceof String && hrefObject instanceof String) {
-return new Link((String) relObject, (String) hrefObject);
+Object titleObject = linkMap.get("title");
+return new Link((String) relObject, (String) hrefObject,
+titleObject instanceof String ? (String) titleObject : null);
 }
 return null;
 }

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

@@ -67,9 +67,12 @@ private static List<Link> convertToLinks(Object object, String rel) {
 
 private static Link maybeCreateLink(String rel, Object possibleLinkObject) {
 if (possibleLinkObject instanceof Map) {
-Object hrefObject = ((Map<?, ?>) possibleLinkObject).get("href");
+Map<?, ?> possibleLinkMap = (Map<?, ?>) possibleLinkObject;
+Object hrefObject = possibleLinkMap.get("href");
 if (hrefObject instanceof String) {
-return new Link(rel, (String) hrefObject);
+Object titleObject = possibleLinkMap.get("title");
+return new Link(rel, (String) hrefObject,
+titleObject instanceof String ? (String) titleObject : null);
 }
 }
 return null;

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

@@ -53,6 +53,10 @@ public static LinkDescriptor linkWithRel(String rel) {
  * 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

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

@@ -29,15 +29,30 @@ public class Link {
 
 private final String href;
 
+private final String title;
+
 /**
  * Creates a new {@code Link} with the given {@code rel} and {@code href}.
  *
  * @param rel The link's rel
  * @param href The link's href
  */
 public Link(String rel, String href) {
+this(rel, href, null);
+}
+
+/**
+ * Creates a new {@code Link} with the given {@code rel}, {@code href}, and
+ * {@code title}.
+ *
+ * @param rel The link's rel
+ * @param href The link's href
+ * @param title The link's title
+ */
+public Link(String rel, String href, String title) {
 this.rel = rel;
 this.href = href;
+this.title = title;
 }
 
 /**
@@ -56,12 +71,21 @@ public String getHref() {
 return this.href;
 }
 
+/**
+ * Returns the link's {@code title}, or {@code null} if it does not have a title.
+ * @return the link's {@code title} or {@code null}
+ */
+public String getTitle() {
+return this.title;
+}
+
 @Override
 public int hashCode() {
-int prime = 31;
+final int prime = 31;
 int result = 1;
 result = prime * result + this.href.hashCode();
 result = prime * result + this.rel.hashCode();
+result = prime * result + ((this.title == null) ? 0 : this.title.hashCode());
 return result;
 }
 
@@ -83,13 +107,21 @@ public boolean equals(Object obj) {
 if (!this.rel.equals(other.rel)) {
 return false;
 }
+if (this.title == null) {
+if (other.title != null) {
+return false;
+}
+}
+else if (!this.title.equals(other.title)) {
+return false;
+}
 return true;
 }
 
 @Override
 public String toString() {
 return new ToStringCreator(this).append("rel", this.rel).append("href", this.href)
-.toString();
+.append("title", this.title).toString();
 }
 
 }

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

@@ -77,27 +77,23 @@ protected LinksSnippet(LinkExtractor linkExtractor, List<LinkDescriptor> descrip
 this.linkExtractor = linkExtractor;
 for (LinkDescriptor descriptor : descriptors) {
 Assert.notNull(descriptor.getRel(), "Link descriptors must have a rel");
-if (!descriptor.isIgnored()) {
-Assert.notNull(descriptor.getDescription(),
-"The descriptor for link '" + descriptor.getRel()
-+ "' must either have a description or be" + " marked as "
-+ "ignored");
-}
 this.descriptorsByRel.put(descriptor.getRel(), descriptor);
 }
 }
 
 @Override
 protected Map<String, Object> createModel(Operation operation) {
 OperationResponse response = operation.getResponse();
+Map<String, List<Link>> links;
 try {
-validate(this.linkExtractor.extractLinks(response));
+links = this.linkExtractor.extractLinks(response);
+validate(links);
 }
 catch (IOException ex) {
 throw new ModelCreationException(ex);
 }
 Map<String, Object> model = new HashMap<>();
-model.put("links", createLinksModel());
+model.put("links", createLinksModel(links));
 return model;
 }
 
@@ -135,17 +131,48 @@ private void validate(Map<String, List<Link>> links) {
 }
 }
 
-private List<Map<String, Object>> createLinksModel() {
+private List<Map<String, Object>> createLinksModel(Map<String, List<Link>> links) {
 List<Map<String, Object>> model = new ArrayList<>();
 for (Entry<String, LinkDescriptor> entry : this.descriptorsByRel.entrySet()) {
 LinkDescriptor descriptor = entry.getValue();
 if (!descriptor.isIgnored()) {
+if (descriptor.getDescription() == null) {
+descriptor = createDescriptor(
+getDescriptionFromLinkTitle(links, descriptor.getRel()),
+descriptor);
+}
 model.add(createModelForDescriptor(descriptor));
 }
 }
 return model;
 }
 
+private String getDescriptionFromLinkTitle(Map<String, List<Link>> links,
+String rel) {
+List<Link> linksForRel = links.get(rel);
+if (linksForRel != null) {
+for (Link link : linksForRel) {
+if (link.getTitle() != null) {
+return link.getTitle();
+}
+}
+}
+throw new SnippetException("No description was provided for the link with rel '"
++ rel + "' and no title was available from the link in the payload");
+}
+
+private LinkDescriptor createDescriptor(String description, LinkDescriptor source) {
+LinkDescriptor newDescriptor = new LinkDescriptor(source.getRel())
+.description(description);
+if (source.isOptional()) {
+newDescriptor.optional();
+}
+if (source.isIgnored()) {
+newDescriptor.ignored();
+}
+return newDescriptor;
+}
+
 /**
  * Returns a {@code Map} of {@link LinkDescriptor LinkDescriptors} keyed by their
  * {@link LinkDescriptor#getRel() rels}.

spring-restdocs-core/src/test/java/org/springframework/restdocs/hypermedia/LinkExtractorsPayloadTests.java

@@ -68,22 +68,24 @@ public LinkExtractorsPayloadTests(LinkExtractor linkExtractor, String linkType)
 public void singleLink() throws IOException {
 Map<String, List<Link>> links = this.linkExtractor
 .extractLinks(createResponse("single-link"));
-assertLinks(Arrays.asList(new Link("alpha", "http://alpha.example.com")), links);
+assertLinks(Arrays.asList(new Link("alpha", "http://alpha.example.com", "Alpha")),
+links);
 }
 
 @Test
 public void multipleLinksWithDifferentRels() throws IOException {
 Map<String, List<Link>> links = this.linkExtractor
 .extractLinks(createResponse("multiple-links-different-rels"));
-assertLinks(Arrays.asList(new Link("alpha", "http://alpha.example.com"),
+assertLinks(Arrays.asList(new Link("alpha", "http://alpha.example.com", "Alpha"),
 new Link("bravo", "http://bravo.example.com")), links);
 }
 
 @Test
 public void multipleLinksWithSameRels() throws IOException {
 Map<String, List<Link>> links = this.linkExtractor
 .extractLinks(createResponse("multiple-links-same-rels"));
-assertLinks(Arrays.asList(new Link("alpha", "http://alpha.example.com/one"),
+assertLinks(Arrays.asList(
+new Link("alpha", "http://alpha.example.com/one", "Alpha one"),
 new Link("alpha", "http://alpha.example.com/two")), links);
 }
 

spring-restdocs-core/src/test/java/org/springframework/restdocs/hypermedia/LinksSnippetFailureTests.java

@@ -79,4 +79,16 @@ public void undocumentedLinkAndMissingLink() throws IOException {
 this.snippet.getOutputDirectory()).build());
 }
 
+@Test
+public void linkWithNoDescription() throws IOException {
+this.thrown.expect(SnippetException.class);
+this.thrown.expectMessage(
+equalTo("No description was provided for the link with rel 'foo' and no"
++ " title was available from the link in the payload"));
+new LinksSnippet(new StubLinkExtractor().withLinks(new Link("foo", "bar")),
+Arrays.asList(new LinkDescriptor("foo")))
+.document(new OperationBuilder("link-with-no-description",
+this.snippet.getOutputDirectory()).build());
+}
+
 }

spring-restdocs-core/src/test/java/org/springframework/restdocs/hypermedia/LinksSnippetTests.java

@@ -87,6 +87,20 @@ public void documentedLinks() throws IOException {
 .document(operationBuilder("documented-links").build());
 }
 
+@Test
+public void linkDescriptionFromTitleInPayload() throws IOException {
+this.snippet.expectLinks("link-description-from-title-in-payload")
+.withContents(tableWithHeader("Relation", "Description").row("a", "one")
+.row("b", "Link b"));
+new LinksSnippet(
+new StubLinkExtractor().withLinks(new Link("a", "alpha", "Link a"),
+new Link("b", "bravo", "Link b")),
+Arrays.asList(new LinkDescriptor("a").description("one"),
+new LinkDescriptor("b"))).document(
+operationBuilder("link-description-from-title-in-payload")
+.build());
+}
+
 @Test
 public void linksWithCustomAttributes() throws IOException {
 TemplateResourceResolver resolver = mock(TemplateResourceResolver.class);

spring-restdocs-core/src/test/resources/link-payloads/atom/multiple-links-different-rels.json

@@ -1,7 +1,8 @@
 {
 "links": [ {
 "rel": "alpha",
-"href": "http://alpha.example.com"
+"href": "http://alpha.example.com",
+"title": "Alpha"
 }, {
 "rel": "bravo",
 "href": "http://bravo.example.com"