How to use

org.springframework.restdocs.hypermedia.LinkDescriptor

constructor

/**
 * Creates a {@code LinkDescriptor} that describes a link with the given {@code rel}.
 * @param rel the rel of the link
 * @return a {@code LinkDescriptor} ready for further configuration
 */
public static LinkDescriptor linkWithRel(String rel) {
  return new LinkDescriptor(rel);
}

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;
}

@Test
public void missingLink() throws IOException {
  this.thrown.expect(SnippetException.class);
  this.thrown.expectMessage(equalTo("Links with the following relations were not"
      + " found in the response: [foo]"));
  new LinksSnippet(new StubLinkExtractor(),
      Arrays.asList(new LinkDescriptor("foo").description("bar")))
          .document(this.operationBuilder.build());
}

@Test
public void ignoredLink() throws IOException {
  new LinksSnippet(
      new StubLinkExtractor().withLinks(new Link("a", "alpha"),
          new Link("b", "bravo")),
      Arrays.asList(new LinkDescriptor("a").ignored(),
          new LinkDescriptor("b").description("Link b")))
              .document(this.operationBuilder.build());
  assertThat(this.generatedSnippets.links())
      .is(tableWithHeader("Relation", "Description").row("`b`", "Link b"));
}

@Test
public void linkDescriptionFromTitleInPayload() throws IOException {
  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(this.operationBuilder.build());
  assertThat(this.generatedSnippets.links())
      .is(tableWithHeader("Relation", "Description").row("`a`", "one")
          .row("`b`", "Link b"));
}

@Test
public void documentedLinks() throws IOException {
  new LinksSnippet(
      new StubLinkExtractor().withLinks(new Link("a", "alpha"),
          new Link("b", "bravo")),
      Arrays.asList(new LinkDescriptor("a").description("one"),
          new LinkDescriptor("b").description("two")))
              .document(this.operationBuilder.build());
  assertThat(this.generatedSnippets.links())
      .is(tableWithHeader("Relation", "Description").row("`a`", "one")
          .row("`b`", "two"));
}

@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(this.operationBuilder.build());
}

@Test
public void undocumentedLinkAndMissingLink() throws IOException {
  this.thrown.expect(SnippetException.class);
  this.thrown.expectMessage(equalTo("Links with the following relations were not"
      + " documented: [a]. Links with the following relations were not"
      + " found in the response: [foo]"));
  new LinksSnippet(new StubLinkExtractor().withLinks(new Link("a", "alpha")),
      Arrays.asList(new LinkDescriptor("foo").description("bar")))
          .document(this.operationBuilder.build());
}

@Test
public void missingOptionalLink() throws IOException {
  new LinksSnippet(new StubLinkExtractor(),
      Arrays.asList(new LinkDescriptor("foo").description("bar").optional()))
          .document(this.operationBuilder.build());
  assertThat(this.generatedSnippets.links())
      .is(tableWithHeader("Relation", "Description").row("`foo`", "bar"));
}

@Test
public void linksWithCustomAttributes() throws IOException {
  TemplateResourceResolver resolver = mock(TemplateResourceResolver.class);
  given(resolver.resolveTemplateResource("links"))
      .willReturn(snippetResource("links-with-title"));
  new LinksSnippet(
      new StubLinkExtractor().withLinks(new Link("a", "alpha"),
          new Link("b", "bravo")),
      Arrays.asList(new LinkDescriptor("a").description("one"),
          new LinkDescriptor("b").description("two")),
      attributes(key("title").value("Title for the links")))
          .document(
              this.operationBuilder
                  .attribute(TemplateEngine.class.getName(),
                      new MustacheTemplateEngine(resolver))
                  .build());
  assertThat(this.generatedSnippets.links()).contains("Title for the links");
}

@Test
public void presentOptionalLink() throws IOException {
  new LinksSnippet(new StubLinkExtractor().withLinks(new Link("foo", "blah")),
      Arrays.asList(new LinkDescriptor("foo").description("bar").optional()))
          .document(this.operationBuilder.build());
  assertThat(this.generatedSnippets.links())
      .is(tableWithHeader("Relation", "Description").row("`foo`", "bar"));
}

@Test
public void tableCellContentIsEscapedWhenNecessary() throws IOException {
  new LinksSnippet(new StubLinkExtractor().withLinks(new Link("Foo|Bar", "foo")),
      Arrays.asList(new LinkDescriptor("Foo|Bar").description("one|two")))
          .document(this.operationBuilder.build());
  assertThat(this.generatedSnippets.links())
      .is(tableWithHeader("Relation", "Description").row(
          escapeIfNecessary("`Foo|Bar`"), escapeIfNecessary("one|two")));
}

@Test
public void allUndocumentedLinksCanBeIgnored() throws IOException {
  new LinksSnippet(
      new StubLinkExtractor().withLinks(new Link("a", "alpha"),
          new Link("b", "bravo")),
      Arrays.asList(new LinkDescriptor("b").description("Link b")), true)
          .document(this.operationBuilder.build());
  assertThat(this.generatedSnippets.links())
      .is(tableWithHeader("Relation", "Description").row("`b`", "Link b"));
}

@Test
public void additionalDescriptors() throws IOException {
  HypermediaDocumentation
      .links(new StubLinkExtractor().withLinks(new Link("a", "alpha"),
          new Link("b", "bravo")),
          new LinkDescriptor("a").description("one"))
      .and(new LinkDescriptor("b").description("two"))
      .document(this.operationBuilder.build());
  assertThat(this.generatedSnippets.links())
      .is(tableWithHeader("Relation", "Description").row("`a`", "one")
          .row("`b`", "two"));
}

@Test
public void linksWithCustomDescriptorAttributes() throws IOException {
  TemplateResourceResolver resolver = mock(TemplateResourceResolver.class);
  given(resolver.resolveTemplateResource("links"))
      .willReturn(snippetResource("links-with-extra-column"));
  new LinksSnippet(
      new StubLinkExtractor().withLinks(new Link("a", "alpha"),
          new Link("b", "bravo")),
      Arrays.asList(
          new LinkDescriptor("a").description("one")
              .attributes(key("foo").value("alpha")),
          new LinkDescriptor("b").description("two")
              .attributes(key("foo").value("bravo"))))
                  .document(this.operationBuilder.attribute(
                      TemplateEngine.class.getName(),
                      new MustacheTemplateEngine(resolver))
                      .build());
  assertThat(this.generatedSnippets.links())
      .is(tableWithHeader("Relation", "Description", "Foo")
          .row("a", "one", "alpha").row("b", "two", "bravo"));
}