Package org.springframework.restdocs.hypermedia

Class HypermediaDocumentation

java.lang.Object
org.springframework.restdocs.hypermedia.HypermediaDocumentation
public abstract class HypermediaDocumentation extends Object
Static factory methods for documenting a RESTful API that utilizes Hypermedia.
Author:
Andy Wilkinson, Marcel Overdijk

  • Method Details

    • linkWithRel

      public static LinkDescriptor linkWithRel(String rel)
      Creates a LinkDescriptor that describes a link with the given rel.
      Parameters:
      rel - the rel of the link
      Returns:
      a LinkDescriptor ready for further configuration

    • links

      public static LinksSnippet links(LinkDescriptor... descriptors)
      Returns a new 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 descriptors.

      If a link is present in the response, but is not documented by one of the descriptors, a failure will occur when the snippet is invoked. Similarly, if a link is documented, is not marked as optional, and is not present in the response, a failure will also occur.

      If you do not want to document a link, a link descriptor can be marked as IgnorableDescriptor.ignored. This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      If a descriptor does not have a description, the title of the link will be used. If the link does not have a title a failure will occur.

      Parameters:
      descriptors - the descriptions of the response's links
      Returns:
      the snippet that will document the links

    • links

      public static LinksSnippet links(List<LinkDescriptor> descriptors)
      Returns a new 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 descriptors.

      If a link is present in the response, but is not documented by one of the descriptors, a failure will occur when the snippet is invoked. Similarly, if a link is documented, is not marked as optional, and is not present in the response, a failure will also occur.

      If you do not want to document a link, a link descriptor can be marked as IgnorableDescriptor.ignored. This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      If a descriptor does not have a description, the title of the link will be used. If the link does not have a title a failure will occur.

      Parameters:
      descriptors - the descriptions of the response's links
      Returns:
      the snippet that will document the links

    • relaxedLinks

      public static LinksSnippet relaxedLinks(LinkDescriptor... descriptors)
      Returns a new 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 descriptors.

      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.

      If a descriptor does not have a description, the title of the link will be used. If the link does not have a title a failure will occur.

      Parameters:
      descriptors - the descriptions of the response's links
      Returns:
      the snippet that will document the links

    • relaxedLinks

      public static LinksSnippet relaxedLinks(List<LinkDescriptor> descriptors)
      Returns a new 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 descriptors.

      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.

      If a descriptor does not have a description, the title of the link will be used. If the link does not have a title a failure will occur.

      Parameters:
      descriptors - the descriptions of the response's links
      Returns:
      the snippet that will document the links

    • links

      public static LinksSnippet links(Map<String,Object> attributes, LinkDescriptor... descriptors)
      Returns a new Snippet that will document the links in the API call's response. The given 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 descriptors.

      If a link is present in the response, but is not documented by one of the descriptors, a failure will occur when the snippet is invoked. Similarly, if a link is documented, is not marked as optional, and is not present in the response, a failure will also occur.

      If you do not want to document a link, a link descriptor can be marked as IgnorableDescriptor.ignored. This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      If a descriptor does not have a description, the title of the link will be used. If the link does not have a title a failure will occur.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the response's links
      Returns:
      the snippet that will document the links

    • links

      public static LinksSnippet links(Map<String,Object> attributes, List<LinkDescriptor> descriptors)
      Returns a new Snippet that will document the links in the API call's response. The given 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 descriptors.

      If a link is present in the response, but is not documented by one of the descriptors, a failure will occur when the snippet is invoked. Similarly, if a link is documented, is not marked as optional, and is not present in the response, a failure will also occur.

      If you do not want to document a link, a link descriptor can be marked as IgnorableDescriptor.ignored. This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      If a descriptor does not have a description, the title of the link will be used. If the link does not have a title a failure will occur.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the response's links
      Returns:
      the snippet that will document the links

    • relaxedLinks

      public static LinksSnippet relaxedLinks(Map<String,Object> attributes, LinkDescriptor... descriptors)
      Returns a new Snippet that will document the links in the API call's response. The given 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 descriptors.

      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.

      If a descriptor does not have a description, the title of the link will be used. If the link does not have a title a failure will occur.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the response's links
      Returns:
      the snippet that will document the links

    • relaxedLinks

      public static LinksSnippet relaxedLinks(Map<String,Object> attributes, List<LinkDescriptor> descriptors)
      Returns a new Snippet that will document the links in the API call's response. The given 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 descriptors.

      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.

      If a descriptor does not have a description, the title of the link will be used. If the link does not have a title a failure will occur.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the response's links
      Returns:
      the snippet that will document the links

    • links

      public static LinksSnippet links(LinkExtractor linkExtractor, LinkDescriptor... descriptors)
      Returns a new Snippet that will document the links in the API operation's response. Links will be extracted from the response using the given linkExtractor and will be documented using the given descriptors.

      If a link is present in the response, but is not documented by one of the descriptors, a failure will occur when the snippet is invoked. Similarly, if a link is documented, is not marked as optional, and is not present in the response, a failure will also occur.

      If you do not want to document a link, a link descriptor can be marked as IgnorableDescriptor.ignored. This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      If a descriptor does not have a description, the title of the link will be used. If the link does not have a title a failure will occur.

      Parameters:
      linkExtractor - used to extract the links from the response
      descriptors - the descriptions of the response's links
      Returns:
      the snippet that will document the links

    • links

      public static LinksSnippet links(LinkExtractor linkExtractor, List<LinkDescriptor> descriptors)
      Returns a new Snippet that will document the links in the API operation's response. Links will be extracted from the response using the given linkExtractor and will be documented using the given descriptors.

      If a link is present in the response, but is not documented by one of the descriptors, a failure will occur when the snippet is invoked. Similarly, if a link is documented, is not marked as optional, and is not present in the response, a failure will also occur.

      If you do not want to document a link, a link descriptor can be marked as IgnorableDescriptor.ignored. This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      If a descriptor does not have a description, the title of the link will be used. If the link does not have a title a failure will occur.

      Parameters:
      linkExtractor - used to extract the links from the response
      descriptors - the descriptions of the response's links
      Returns:
      the snippet that will document the links

    • relaxedLinks

      public static LinksSnippet relaxedLinks(LinkExtractor linkExtractor, LinkDescriptor... descriptors)
      Returns a new Snippet that will document the links in the API operation's response. Links will be extracted from the response using the given linkExtractor and will be documented using the given descriptors.

      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.

      If a descriptor does not have a description, the title of the link will be used. If the link does not have a title a failure will occur.

      Parameters:
      linkExtractor - used to extract the links from the response
      descriptors - the descriptions of the response's links
      Returns:
      the snippet that will document the links

    • relaxedLinks

      public static LinksSnippet relaxedLinks(LinkExtractor linkExtractor, List<LinkDescriptor> descriptors)
      Returns a new Snippet that will document the links in the API operation's response. Links will be extracted from the response using the given linkExtractor and will be documented using the given descriptors.

      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.

      If a descriptor does not have a description, the title of the link will be used. If the link does not have a title a failure will occur.

      Parameters:
      linkExtractor - used to extract the links from the response
      descriptors - the descriptions of the response's links
      Returns:
      the snippet that will document the links

    • links

      public static LinksSnippet links(LinkExtractor linkExtractor, Map<String,Object> attributes, LinkDescriptor... descriptors)
      Returns a new Snippet that will document the links in the API operation's response. The given attributes will be available during snippet generation. Links will be extracted from the response using the given linkExtractor and will be documented using the given descriptors.

      If a link is present in the response, but is not documented by one of the descriptors, a failure will occur when the snippet is invoked. Similarly, if a link is documented, is not marked as optional, and is not present in the response, a failure will also occur.

      If you do not want to document a link, a link descriptor can be marked as IgnorableDescriptor.ignored. This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      If a descriptor does not have a description, the title of the link will be used. If the link does not have a title a failure will occur.

      Parameters:
      attributes - the attributes
      linkExtractor - used to extract the links from the response
      descriptors - the descriptions of the response's links
      Returns:
      the snippet that will document the links

    • links

      public static LinksSnippet links(LinkExtractor linkExtractor, Map<String,Object> attributes, List<LinkDescriptor> descriptors)
      Returns a new Snippet that will document the links in the API operation's response. The given attributes will be available during snippet generation. Links will be extracted from the response using the given linkExtractor and will be documented using the given descriptors.

      If a link is present in the response, but is not documented by one of the descriptors, a failure will occur when the snippet is invoked. Similarly, if a link is documented, is not marked as optional, and is not present in the response, a failure will also occur.

      If you do not want to document a link, a link descriptor can be marked as IgnorableDescriptor.ignored. This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      If a descriptor does not have a description, the title of the link will be used. If the link does not have a title a failure will occur.

      Parameters:
      attributes - the attributes
      linkExtractor - used to extract the links from the response
      descriptors - the descriptions of the response's links
      Returns:
      the snippet that will document the links

    • relaxedLinks

      public static LinksSnippet relaxedLinks(LinkExtractor linkExtractor, Map<String,Object> attributes, LinkDescriptor... descriptors)
      Returns a new Snippet that will document the links in the API operation's response. The given attributes will be available during snippet generation. Links will be extracted from the response using the given linkExtractor and will be documented using the given descriptors.

      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.

      If a descriptor does not have a description, the title of the link will be used. If the link does not have a title a failure will occur.

      Parameters:
      attributes - the attributes
      linkExtractor - used to extract the links from the response
      descriptors - the descriptions of the response's links
      Returns:
      the snippet that will document the links

    • relaxedLinks

      public static LinksSnippet relaxedLinks(LinkExtractor linkExtractor, Map<String,Object> attributes, List<LinkDescriptor> descriptors)
      Returns a new Snippet that will document the links in the API operation's response. The given attributes will be available during snippet generation. Links will be extracted from the response using the given linkExtractor and will be documented using the given descriptors.

      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.

      If a descriptor does not have a description, the title of the link will be used. If the link does not have a title a failure will occur.

      Parameters:
      attributes - the attributes
      linkExtractor - used to extract the links from the response
      descriptors - the descriptions of the response's links
      Returns:
      the snippet that will document the links

    • halLinks

      public static LinkExtractor halLinks()
      Returns a LinkExtractor capable of extracting links in Hypermedia Application Language (HAL) format where the links are found in a map named _links. For example: 
       {
     "_links": {
         "self": {
             "href": "https://example.com/foo"
         }
     }
 }
      Returns:
      the extractor for HAL-style links

    • atomLinks

      public static LinkExtractor atomLinks()
      Returns a LinkExtractor capable of extracting links in Atom format where the links are found in an array named links. For example: 
       {
     "links": [
         {
             "rel": "self",
             "href": "https://example.com/foo"
         }
     ]
 }
      Returns:
      the extractor for Atom-style links