org.springframework.restdocs.hypermedia.HypermediaDocumentation.java Source code

Introduction

Here is the source code for org.springframework.restdocs.hypermedia.HypermediaDocumentation.java

Source

/*
 * Copyright 2014-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.restdocs.hypermedia;

import java.util.Arrays;
import java.util.List;
import java.util.Map;

/**
 * Static factory methods for documenting a RESTful API that utilizes Hypermedia.
 *
 * @author Andy Wilkinson
 * @author Marcel Overdijk
 */
public abstract class HypermediaDocumentation {

    private HypermediaDocumentation() {

    }

    /**
     * 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);
    }

    /**
     * Returns a new {@code 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 {@code descriptors}.
     * <p>
     * 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.
     * <p>
     * If you do not want to document a link, a link descriptor can be marked as
     * {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
     * generated snippet while avoiding the failure described above.
     * <p>
     * If a descriptor does not have a {@link LinkDescriptor#description(Object)
     * description}, the {@link Link#getTitle() title} of the link will be used. If the
     * link does not have a title a failure will occur.
     * @param descriptors the descriptions of the response's links
     * @return the snippet that will document the links
     */
    public static LinksSnippet links(LinkDescriptor... descriptors) {
        return links(Arrays.asList(descriptors));
    }

    /**
     * Returns a new {@code 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 {@code descriptors}.
     * <p>
     * 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.
     * <p>
     * If you do not want to document a link, a link descriptor can be marked as
     * {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
     * generated snippet while avoiding the failure described above.
     * <p>
     * If a descriptor does not have a {@link LinkDescriptor#description(Object)
     * description}, the {@link Link#getTitle() title} of the link will be used. If the
     * link does not have a title a failure will occur.
     * @param descriptors the descriptions of the response's links
     * @return the snippet that will document the links
     */
    public static LinksSnippet links(List<LinkDescriptor> descriptors) {
        return new LinksSnippet(new ContentTypeLinkExtractor(), descriptors);
    }

    /**
     * Returns a new {@code 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 {@code descriptors}.
     * <p>
     * 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.
     * <p>
     * If a descriptor does not have a {@link LinkDescriptor#description(Object)
     * description}, the {@link Link#getTitle() title} of the link will be used. If the
     * link does not have a title a failure will occur.
     * @param descriptors the descriptions of the response's links
     * @return the snippet that will document the links
     */
    public static LinksSnippet relaxedLinks(LinkDescriptor... descriptors) {
        return relaxedLinks(Arrays.asList(descriptors));
    }

    /**
     * Returns a new {@code 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 {@code descriptors}.
     * <p>
     * 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.
     * <p>
     * If a descriptor does not have a {@link LinkDescriptor#description(Object)
     * description}, the {@link Link#getTitle() title} of the link will be used. If the
     * link does not have a title a failure will occur.
     * @param descriptors the descriptions of the response's links
     * @return the snippet that will document the links
     */
    public static LinksSnippet relaxedLinks(List<LinkDescriptor> descriptors) {
        return new LinksSnippet(new ContentTypeLinkExtractor(), descriptors, true);
    }

    /**
     * Returns a new {@code Snippet} that will document the links in the API call's
     * response. The given {@code 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 {@code descriptors}.
     * <p>
     * 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.
     * <p>
     * If you do not want to document a link, a link descriptor can be marked as
     * {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
     * generated snippet while avoiding the failure described above.
     * <p>
     * If a descriptor does not have a {@link LinkDescriptor#description(Object)
     * description}, the {@link Link#getTitle() title} of the link will be used. If the
     * link does not have a title a failure will occur.
     * @param attributes the attributes
     * @param descriptors the descriptions of the response's links
     * @return the snippet that will document the links
     */
    public static LinksSnippet links(Map<String, Object> attributes, LinkDescriptor... descriptors) {
        return links(attributes, Arrays.asList(descriptors));
    }

    /**
     * Returns a new {@code Snippet} that will document the links in the API call's
     * response. The given {@code 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 {@code descriptors}.
     * <p>
     * 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.
     * <p>
     * If you do not want to document a link, a link descriptor can be marked as
     * {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
     * generated snippet while avoiding the failure described above.
     * <p>
     * If a descriptor does not have a {@link LinkDescriptor#description(Object)
     * description}, the {@link Link#getTitle() title} of the link will be used. If the
     * link does not have a title a failure will occur.
     * @param attributes the attributes
     * @param descriptors the descriptions of the response's links
     * @return the snippet that will document the links
     */
    public static LinksSnippet links(Map<String, Object> attributes, List<LinkDescriptor> descriptors) {
        return new LinksSnippet(new ContentTypeLinkExtractor(), descriptors, attributes);
    }

    /**
     * Returns a new {@code Snippet} that will document the links in the API call's
     * response. The given {@code 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 {@code descriptors}.
     * <p>
     * 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.
     * <p>
     * If a descriptor does not have a {@link LinkDescriptor#description(Object)
     * description}, the {@link Link#getTitle() title} of the link will be used. If the
     * link does not have a title a failure will occur.
     * @param attributes the attributes
     * @param descriptors the descriptions of the response's links
     * @return the snippet that will document the links
     */
    public static LinksSnippet relaxedLinks(Map<String, Object> attributes, LinkDescriptor... descriptors) {
        return relaxedLinks(attributes, Arrays.asList(descriptors));
    }

    /**
     * Returns a new {@code Snippet} that will document the links in the API call's
     * response. The given {@code 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 {@code descriptors}.
     * <p>
     * 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.
     * <p>
     * If a descriptor does not have a {@link LinkDescriptor#description(Object)
     * description}, the {@link Link#getTitle() title} of the link will be used. If the
     * link does not have a title a failure will occur.
     * @param attributes the attributes
     * @param descriptors the descriptions of the response's links
     * @return the snippet that will document the links
     */
    public static LinksSnippet relaxedLinks(Map<String, Object> attributes, List<LinkDescriptor> descriptors) {
        return new LinksSnippet(new ContentTypeLinkExtractor(), descriptors, attributes, true);
    }

    /**
     * Returns a new {@code Snippet} that will document the links in the API operation's
     * response. Links will be extracted from the response using the given
     * {@code linkExtractor} and will be documented using the given {@code descriptors}.
     * <p>
     * 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.
     * <p>
     * If you do not want to document a link, a link descriptor can be marked as
     * {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
     * generated snippet while avoiding the failure described above.
     * <p>
     * If a descriptor does not have a {@link LinkDescriptor#description(Object)
     * description}, the {@link Link#getTitle() title} of the link will be used. If the
     * link does not have a title a failure will occur.
     * @param linkExtractor used to extract the links from the response
     * @param descriptors the descriptions of the response's links
     * @return the snippet that will document the links
     */
    public static LinksSnippet links(LinkExtractor linkExtractor, LinkDescriptor... descriptors) {
        return links(linkExtractor, Arrays.asList(descriptors));
    }

    /**
     * Returns a new {@code Snippet} that will document the links in the API operation's
     * response. Links will be extracted from the response using the given
     * {@code linkExtractor} and will be documented using the given {@code descriptors}.
     * <p>
     * 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.
     * <p>
     * If you do not want to document a link, a link descriptor can be marked as
     * {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
     * generated snippet while avoiding the failure described above.
     * <p>
     * If a descriptor does not have a {@link LinkDescriptor#description(Object)
     * description}, the {@link Link#getTitle() title} of the link will be used. If the
     * link does not have a title a failure will occur.
     * @param linkExtractor used to extract the links from the response
     * @param descriptors the descriptions of the response's links
     * @return the snippet that will document the links
     */
    public static LinksSnippet links(LinkExtractor linkExtractor, List<LinkDescriptor> descriptors) {
        return new LinksSnippet(linkExtractor, descriptors);
    }

    /**
     * Returns a new {@code Snippet} that will document the links in the API operation's
     * response. Links will be extracted from the response using the given
     * {@code linkExtractor} and will be documented using the given {@code descriptors}.
     * <p>
     * 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.
     * <p>
     * If a descriptor does not have a {@link LinkDescriptor#description(Object)
     * description}, the {@link Link#getTitle() title} of the link will be used. If the
     * link does not have a title a failure will occur.
     * @param linkExtractor used to extract the links from the response
     * @param descriptors the descriptions of the response's links
     * @return the snippet that will document the links
     */
    public static LinksSnippet relaxedLinks(LinkExtractor linkExtractor, LinkDescriptor... descriptors) {
        return relaxedLinks(linkExtractor, Arrays.asList(descriptors));
    }

    /**
     * Returns a new {@code Snippet} that will document the links in the API operation's
     * response. Links will be extracted from the response using the given
     * {@code linkExtractor} and will be documented using the given {@code descriptors}.
     * <p>
     * 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.
     * <p>
     * If a descriptor does not have a {@link LinkDescriptor#description(Object)
     * description}, the {@link Link#getTitle() title} of the link will be used. If the
     * link does not have a title a failure will occur.
     * @param linkExtractor used to extract the links from the response
     * @param descriptors the descriptions of the response's links
     * @return the snippet that will document the links
     */
    public static LinksSnippet relaxedLinks(LinkExtractor linkExtractor, List<LinkDescriptor> descriptors) {
        return new LinksSnippet(linkExtractor, descriptors, true);
    }

    /**
     * Returns a new {@code Snippet} that will document the links in the API operation's
     * response. The given {@code attributes} will be available during snippet generation.
     * Links will be extracted from the response using the given {@code linkExtractor} and
     * will be documented using the given {@code descriptors}.
     * <p>
     * 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.
     * <p>
     * If you do not want to document a link, a link descriptor can be marked as
     * {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
     * generated snippet while avoiding the failure described above.
     * <p>
     * If a descriptor does not have a {@link LinkDescriptor#description(Object)
     * description}, the {@link Link#getTitle() title} of the link will be used. If the
     * link does not have a title a failure will occur.
     * @param attributes the attributes
     * @param linkExtractor used to extract the links from the response
     * @param descriptors the descriptions of the response's links
     * @return the snippet that will document the links
     */
    public static LinksSnippet links(LinkExtractor linkExtractor, Map<String, Object> attributes,
            LinkDescriptor... descriptors) {
        return links(linkExtractor, attributes, Arrays.asList(descriptors));
    }

    /**
     * Returns a new {@code Snippet} that will document the links in the API operation's
     * response. The given {@code attributes} will be available during snippet generation.
     * Links will be extracted from the response using the given {@code linkExtractor} and
     * will be documented using the given {@code descriptors}.
     * <p>
     * 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.
     * <p>
     * If you do not want to document a link, a link descriptor can be marked as
     * {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
     * generated snippet while avoiding the failure described above.
     * <p>
     * If a descriptor does not have a {@link LinkDescriptor#description(Object)
     * description}, the {@link Link#getTitle() title} of the link will be used. If the
     * link does not have a title a failure will occur.
     * @param attributes the attributes
     * @param linkExtractor used to extract the links from the response
     * @param descriptors the descriptions of the response's links
     * @return the snippet that will document the links
     */
    public static LinksSnippet links(LinkExtractor linkExtractor, Map<String, Object> attributes,
            List<LinkDescriptor> descriptors) {
        return new LinksSnippet(linkExtractor, descriptors, attributes);
    }

    /**
     * Returns a new {@code Snippet} that will document the links in the API operation's
     * response. The given {@code attributes} will be available during snippet generation.
     * Links will be extracted from the response using the given {@code linkExtractor} and
     * will be documented using the given {@code descriptors}.
     * <p>
     * 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.
     * <p>
     * If a descriptor does not have a {@link LinkDescriptor#description(Object)
     * description}, the {@link Link#getTitle() title} of the link will be used. If the
     * link does not have a title a failure will occur.
     * @param attributes the attributes
     * @param linkExtractor used to extract the links from the response
     * @param descriptors the descriptions of the response's links
     * @return the snippet that will document the links
     */
    public static LinksSnippet relaxedLinks(LinkExtractor linkExtractor, Map<String, Object> attributes,
            LinkDescriptor... descriptors) {
        return relaxedLinks(linkExtractor, attributes, Arrays.asList(descriptors));
    }

    /**
     * Returns a new {@code Snippet} that will document the links in the API operation's
     * response. The given {@code attributes} will be available during snippet generation.
     * Links will be extracted from the response using the given {@code linkExtractor} and
     * will be documented using the given {@code descriptors}.
     * <p>
     * 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.
     * <p>
     * If a descriptor does not have a {@link LinkDescriptor#description(Object)
     * description}, the {@link Link#getTitle() title} of the link will be used. If the
     * link does not have a title a failure will occur.
     * @param attributes the attributes
     * @param linkExtractor used to extract the links from the response
     * @param descriptors the descriptions of the response's links
     * @return the snippet that will document the links
     */
    public static LinksSnippet relaxedLinks(LinkExtractor linkExtractor, Map<String, Object> attributes,
            List<LinkDescriptor> descriptors) {
        return new LinksSnippet(linkExtractor, descriptors, attributes, true);
    }

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

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

}