How to use

description

method

in

org.springframework.restdocs.hypermedia.LinkDescriptor

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

public void documentation() throws Exception {
  // tag::use[]
  RestAssured.given(this.spec)
    .accept("application/json")
    .filter(document("example", this.pagingLinks.and( // <1>
        linkWithRel("alpha").description("Link to the alpha resource"),
        linkWithRel("bravo").description("Link to the bravo resource"))))
    .get("/").then().assertThat().statusCode(is(200));
  // end::use[]
}

public void defaultExtractor() throws Exception {
  // tag::links[]
  RestAssured.given(this.spec)
    .accept("application/json")
    .filter(document("index", links( // <1>
        linkWithRel("alpha").description("Link to the alpha resource"), // <2>
        linkWithRel("bravo").description("Link to the bravo resource")))) // <3>
    .get("/").then().assertThat().statusCode(is(200));
  // end::links[]
}

public void explicitExtractor() throws Exception {
  RestAssured.given(this.spec)
  .accept("application/json")
  // tag::explicit-extractor[]
  .filter(document("index", links(halLinks(), // <1>
      linkWithRel("alpha").description("Link to the alpha resource"),
      linkWithRel("bravo").description("Link to the bravo resource"))))
  // end::explicit-extractor[]
  .get("/").then().assertThat().statusCode(is(200));
}

@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());
}

public void documentation() throws Exception {
  // tag::use[]
  this.mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isOk())
    .andDo(document("example", this.pagingLinks.and( // <1>
        linkWithRel("alpha").description("Link to the alpha resource"),
        linkWithRel("bravo").description("Link to the bravo resource"))));
  // end::use[]
}

public void defaultExtractor() throws Exception {
  // tag::links[]
  this.mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isOk())
    .andDo(document("index", links( // <1>
        linkWithRel("alpha").description("Link to the alpha resource"), // <2>
        linkWithRel("bravo").description("Link to the bravo resource")))); // <3>
  // end::links[]
}

public void defaultExtractor() throws Exception {
  // tag::links[]
  this.webTestClient.get().uri("/").accept(MediaType.APPLICATION_JSON).exchange()
    .expectStatus().isOk().expectBody()
    .consumeWith(document("index",links( // <1>
        linkWithRel("alpha").description("Link to the alpha resource"), // <2>
        linkWithRel("bravo").description("Link to the bravo resource")))); // <3>
  // end::links[]
}

public void documentation() throws Exception {
  // tag::use[]
  this.webTestClient.get().uri("/").accept(MediaType.APPLICATION_JSON).exchange()
    .expectStatus().isOk().expectBody()
    .consumeWith(document("example", this.pagingLinks.and( // <1>
      linkWithRel("alpha").description("Link to the alpha resource"),
      linkWithRel("bravo").description("Link to the bravo resource"))));
  // end::use[]
}

public void explicitExtractor() throws Exception {
  this.mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isOk())
    //tag::explicit-extractor[]
    .andDo(document("index", links(halLinks(), // <1>
        linkWithRel("alpha").description("Link to the alpha resource"),
        linkWithRel("bravo").description("Link to the bravo resource"))));
    // end::explicit-extractor[]
}

@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 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 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 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"));
}

public void use() throws Exception {
  // tag::use[]
  this.mockMvc.perform(get("/"))
      .andExpect(status().isOk())
      .andDo(document("index",
          links(linkWithRel("self").description("Canonical self link"))
      ));
  // end::use[]
}

@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 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 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 linksSnippet() throws Exception {
  MockMvc mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
      .apply(documentationConfiguration(this.restDocumentation)).build();
  mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
      .andExpect(status().isOk()).andDo(document("links",
          links(linkWithRel("rel").description("The description"))));
  assertExpectedSnippetFilesExist(new File("build/generated-snippets/links"),
      "http-request.adoc", "http-response.adoc", "curl-request.adoc",
      "links.adoc");
}