Class HypermediaDocumentation
- Author:
- Andy Wilkinson, Marcel Overdijk
-
Method Summary
Modifier and TypeMethodDescriptionstatic LinkExtractorReturns aLinkExtractorcapable of extracting links in Atom format where the links are found in an array namedlinks.static LinkExtractorhalLinks()Returns aLinkExtractorcapable of extracting links in Hypermedia Application Language (HAL) format where the links are found in a map named_links.static LinksSnippetlinks(List<LinkDescriptor> descriptors) Returns a newSnippetthat will document the links in the API operation's response.static LinksSnippetReturns a newSnippetthat will document the links in the API call's response.static LinksSnippetlinks(Map<String, Object> attributes, LinkDescriptor... descriptors) Returns a newSnippetthat will document the links in the API call's response.static LinksSnippetlinks(LinkDescriptor... descriptors) Returns a newSnippetthat will document the links in the API operation's response.static LinksSnippetlinks(LinkExtractor linkExtractor, List<LinkDescriptor> descriptors) Returns a newSnippetthat will document the links in the API operation's response.static LinksSnippetlinks(LinkExtractor linkExtractor, Map<String, Object> attributes, List<LinkDescriptor> descriptors) Returns a newSnippetthat will document the links in the API operation's response.static LinksSnippetlinks(LinkExtractor linkExtractor, Map<String, Object> attributes, LinkDescriptor... descriptors) Returns a newSnippetthat will document the links in the API operation's response.static LinksSnippetlinks(LinkExtractor linkExtractor, LinkDescriptor... descriptors) Returns a newSnippetthat will document the links in the API operation's response.static LinkDescriptorlinkWithRel(String rel) Creates aLinkDescriptorthat describes a link with the givenrel.static LinksSnippetrelaxedLinks(List<LinkDescriptor> descriptors) Returns a newSnippetthat will document the links in the API operation's response.static LinksSnippetrelaxedLinks(Map<String, Object> attributes, List<LinkDescriptor> descriptors) Returns a newSnippetthat will document the links in the API call's response.static LinksSnippetrelaxedLinks(Map<String, Object> attributes, LinkDescriptor... descriptors) Returns a newSnippetthat will document the links in the API call's response.static LinksSnippetrelaxedLinks(LinkDescriptor... descriptors) Returns a newSnippetthat will document the links in the API operation's response.static LinksSnippetrelaxedLinks(LinkExtractor linkExtractor, List<LinkDescriptor> descriptors) Returns a newSnippetthat will document the links in the API operation's response.static LinksSnippetrelaxedLinks(LinkExtractor linkExtractor, Map<String, Object> attributes, List<LinkDescriptor> descriptors) Returns a newSnippetthat will document the links in the API operation's response.static LinksSnippetrelaxedLinks(LinkExtractor linkExtractor, Map<String, Object> attributes, LinkDescriptor... descriptors) Returns a newSnippetthat will document the links in the API operation's response.static LinksSnippetrelaxedLinks(LinkExtractor linkExtractor, LinkDescriptor... descriptors) Returns a newSnippetthat will document the links in the API operation's response.
-
Method Details
-
linkWithRel
Creates aLinkDescriptorthat describes a link with the givenrel.- Parameters:
rel- the rel of the link- Returns:
- a
LinkDescriptorready for further configuration
-
links
Returns a newSnippetthat 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 givendescriptors.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, thetitleof 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
Returns a newSnippetthat 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 givendescriptors.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, thetitleof 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
Returns a newSnippetthat 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 givendescriptors.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, thetitleof 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
Returns a newSnippetthat 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 givendescriptors.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, thetitleof 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
Returns a newSnippetthat will document the links in the API call's response. The givenattributeswill be available during snippet generation. Links will be extracted from the response automatically based on its content type and will be documented using the givendescriptors.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, thetitleof the link will be used. If the link does not have a title a failure will occur.- Parameters:
attributes- the attributesdescriptors- the descriptions of the response's links- Returns:
- the snippet that will document the links
-
links
Returns a newSnippetthat will document the links in the API call's response. The givenattributeswill be available during snippet generation. Links will be extracted from the response automatically based on its content type and will be documented using the givendescriptors.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, thetitleof the link will be used. If the link does not have a title a failure will occur.- Parameters:
attributes- the attributesdescriptors- 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 newSnippetthat will document the links in the API call's response. The givenattributeswill be available during snippet generation. Links will be extracted from the response automatically based on its content type and will be documented using the givendescriptors.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, thetitleof the link will be used. If the link does not have a title a failure will occur.- Parameters:
attributes- the attributesdescriptors- 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 newSnippetthat will document the links in the API call's response. The givenattributeswill be available during snippet generation. Links will be extracted from the response automatically based on its content type and will be documented using the givendescriptors.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, thetitleof the link will be used. If the link does not have a title a failure will occur.- Parameters:
attributes- the attributesdescriptors- the descriptions of the response's links- Returns:
- the snippet that will document the links
-
links
Returns a newSnippetthat will document the links in the API operation's response. Links will be extracted from the response using the givenlinkExtractorand will be documented using the givendescriptors.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, thetitleof 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 responsedescriptors- the descriptions of the response's links- Returns:
- the snippet that will document the links
-
links
Returns a newSnippetthat will document the links in the API operation's response. Links will be extracted from the response using the givenlinkExtractorand will be documented using the givendescriptors.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, thetitleof 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 responsedescriptors- the descriptions of the response's links- Returns:
- the snippet that will document the links
-
relaxedLinks
Returns a newSnippetthat will document the links in the API operation's response. Links will be extracted from the response using the givenlinkExtractorand will be documented using the givendescriptors.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, thetitleof 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 responsedescriptors- 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 newSnippetthat will document the links in the API operation's response. Links will be extracted from the response using the givenlinkExtractorand will be documented using the givendescriptors.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, thetitleof 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 responsedescriptors- 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 newSnippetthat will document the links in the API operation's response. The givenattributeswill be available during snippet generation. Links will be extracted from the response using the givenlinkExtractorand will be documented using the givendescriptors.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, thetitleof the link will be used. If the link does not have a title a failure will occur.- Parameters:
attributes- the attributeslinkExtractor- used to extract the links from the responsedescriptors- 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 newSnippetthat will document the links in the API operation's response. The givenattributeswill be available during snippet generation. Links will be extracted from the response using the givenlinkExtractorand will be documented using the givendescriptors.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, thetitleof the link will be used. If the link does not have a title a failure will occur.- Parameters:
attributes- the attributeslinkExtractor- used to extract the links from the responsedescriptors- 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 newSnippetthat will document the links in the API operation's response. The givenattributeswill be available during snippet generation. Links will be extracted from the response using the givenlinkExtractorand will be documented using the givendescriptors.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, thetitleof the link will be used. If the link does not have a title a failure will occur.- Parameters:
attributes- the attributeslinkExtractor- used to extract the links from the responsedescriptors- 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 newSnippetthat will document the links in the API operation's response. The givenattributeswill be available during snippet generation. Links will be extracted from the response using the givenlinkExtractorand will be documented using the givendescriptors.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, thetitleof the link will be used. If the link does not have a title a failure will occur.- Parameters:
attributes- the attributeslinkExtractor- used to extract the links from the responsedescriptors- the descriptions of the response's links- Returns:
- the snippet that will document the links
-
halLinks
Returns aLinkExtractorcapable 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
Returns aLinkExtractorcapable of extracting links in Atom format where the links are found in an array namedlinks. For example:{ "links": [ { "rel": "self", "href": "https://example.com/foo" } ] }- Returns:
- the extractor for Atom-style links
-