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

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

@@ -68,14 +68,15 @@ public class LinkExtractorsPayloadTests {
 	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);
 	}
 
@@ -83,7 +84,8 @@ public class LinkExtractorsPayloadTests {
 	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 class LinksSnippetFailureTests {
 								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 class LinksSnippetTests extends AbstractSnippetTests {
 								.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"

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

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

spring-restdocs-core/src/test/resources/link-payloads/atom/single-link.json

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

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

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

spring-restdocs-core/src/test/resources/link-payloads/hal/multiple-links-same-rels.json

@@ -1,7 +1,8 @@
 {
 	"_links": {
 		"alpha": [{
-		    "href": "http://alpha.example.com/one"
+		    "href": "http://alpha.example.com/one",
+			"title": "Alpha one"
 		}, {
 		    "href": "http://alpha.example.com/two"
 		}]

spring-restdocs-core/src/test/resources/link-payloads/hal/single-link.json

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