diff --git a/spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/HeaderDocumentation.java b/spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/HeaderDocumentation.java index 1eb4f0f9..740f6a78 100644 --- a/spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/HeaderDocumentation.java +++ b/spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/HeaderDocumentation.java @@ -17,6 +17,7 @@ package org.springframework.restdocs.headers; import java.util.Arrays; +import java.util.List; import java.util.Map; import org.springframework.restdocs.snippet.Snippet; @@ -59,6 +60,21 @@ public abstract class HeaderDocumentation { return new RequestHeadersSnippet(Arrays.asList(descriptors)); } + /** + * Returns a new {@link Snippet} that will document the headers of the API operation's + * request. The headers will be documented using the given {@code descriptors}. + *
+ * If a header is documented, is not marked as optional, and is not present in the
+ * request, a failure will occur.
+ *
+ * @param descriptors the descriptions of the request's headers
+ * @return the snippet that will document the request headers
+ * @see #headerWithName(String)
+ */
+ public static RequestHeadersSnippet requestHeaders(List
+ * If a header is documented, is not marked as optional, and is not present in the
+ * request, a failure will occur.
+ *
+ * @param attributes the attributes
+ * @param descriptors the descriptions of the request's headers
+ * @return the snippet that will document the request headers
+ * @see #headerWithName(String)
+ */
+ public static RequestHeadersSnippet requestHeaders(Map
+ * If a header is documented, is not marked as optional, and is not present in the
+ * request, a failure will occur.
+ *
+ * @param descriptors the descriptions of the response's headers
+ * @return the snippet that will document the response headers
+ * @see #headerWithName(String)
+ */
+ public static ResponseHeadersSnippet responseHeaders(
+ List
+ * If a header is documented, is not marked as optional, and is not present in the
+ * response, a failure will occur.
+ *
+ * @param attributes the attributes
+ * @param descriptors the descriptions of the response's headers
+ * @return the snippet that will document the response headers
+ * @see #headerWithName(String)
+ */
+ public static ResponseHeadersSnippet responseHeaders(Map
+ * 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
+ * {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
+ * generated snippet while avoiding the failure described above.
+ *
+ * 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
+ * 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 {@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
+ * 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
+ * {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
+ * generated snippet while avoiding the failure described above.
+ *
+ * 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
+ * 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 {@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
+ * 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
+ * {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
+ * generated snippet while avoiding the failure described above.
+ *
+ * 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
+ * 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 {@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
+ * 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
+ * {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
+ * generated snippet while avoiding the failure described above.
+ *
+ * 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
+ * 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 {@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
+ * If a field is present in the request payload, but is not documented by one of the
+ * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+ * field is documented, is not marked as optional, and is not present in the request,
+ * a failure will also occur. For payloads with a hierarchical structure, documenting
+ * a field is sufficient for all of its descendants to also be treated as having been
+ * documented.
+ *
+ * If you do not want to document a field, a field descriptor can be marked as
+ * {@link FieldDescriptor#ignored}. This will prevent it from appearing in the
+ * generated snippet while avoiding the failure described above.
+ *
+ * @param descriptors the descriptions of the request payload's fields
+ * @return the snippet that will document the fields
+ * @see #fieldWithPath(String)
+ */
+ public static RequestFieldsSnippet requestFields(List
+ * If a field is documented, is not marked as optional, and is not present in the
+ * request, a failure will occur. Any undocumented fields will be ignored.
+ *
+ * @param descriptors the descriptions of the request payload's fields
+ * @return the snippet that will document the fields
+ * @see #fieldWithPath(String)
+ */
+ public static RequestFieldsSnippet relaxedRequestFields(
+ List
+ * If a field is present in the request payload, but is not documented by one of the
+ * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+ * field is documented, is not marked as optional, and is not present in the request
+ * payload, a failure will also occur. For payloads with a hierarchical structure,
+ * documenting a field is sufficient for all of its descendants to also be treated as
+ * having been documented.
+ *
+ * If you do not want to document a field, a field descriptor can be marked as
+ * {@link FieldDescriptor#ignored}. This will prevent it from appearing in the
+ * generated snippet while avoiding the failure described above.
+ *
+ * @param attributes the attributes
+ * @param descriptors the descriptions of the request payload's fields
+ * @return the snippet that will document the fields
+ * @see #fieldWithPath(String)
+ */
+ public static RequestFieldsSnippet requestFields(Map
+ * If a field is documented, is not marked as optional, and is not present in the
+ * request, a failure will occur. Any undocumented fields will be ignored.
+ *
+ * @param attributes the attributes
+ * @param descriptors the descriptions of the request payload's fields
+ * @return the snippet that will document the fields
+ * @see #fieldWithPath(String)
+ */
+ public static RequestFieldsSnippet relaxedRequestFields(
+ Map
+ * If a field is present in the response payload, but is not documented by one of the
+ * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+ * field is documented, is not marked as optional, and is not present in the response
+ * payload, a failure will also occur. For payloads with a hierarchical structure,
+ * documenting a field is sufficient for all of its descendants to also be treated as
+ * having been documented.
+ *
+ * If you do not want to document a field, a field descriptor can be marked as
+ * {@link FieldDescriptor#ignored}. This will prevent it from appearing in the
+ * generated snippet while avoiding the failure described above.
+ *
+ * @param descriptors the descriptions of the response payload's fields
+ * @return the snippet that will document the fields
+ * @see #fieldWithPath(String)
+ */
+ public static ResponseFieldsSnippet responseFields(List
+ * If a field is documented, is not marked as optional, and is not present in the
+ * request, a failure will occur. Any undocumented fields will be ignored.
+ *
+ * @param descriptors the descriptions of the response payload's fields
+ * @return the snippet that will document the fields
+ * @see #fieldWithPath(String)
+ */
+ public static ResponseFieldsSnippet relaxedResponseFields(
+ List
+ * If a field is present in the response payload, but is not documented by one of the
+ * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+ * field is documented, is not marked as optional, and is not present in the response
+ * payload, a failure will also occur. For payloads with a hierarchical structure,
+ * documenting a field is sufficient for all of its descendants to also be treated as
+ * having been documented.
+ *
+ * If you do not want to document a field, a field descriptor can be marked as
+ * {@link FieldDescriptor#ignored}. This will prevent it from appearing in the
+ * generated snippet while avoiding the failure described above.
+ *
+ * @param attributes the attributes
+ * @param descriptors the descriptions of the response payload's fields
+ * @return the snippet that will document the fields
+ * @see #fieldWithPath(String)
+ */
+ public static ResponseFieldsSnippet responseFields(Map
+ * If a field is documented, is not marked as optional, and is not present in the
+ * request, a failure will occur. Any undocumented fields will be ignored.
+ *
+ * @param attributes the attributes
+ * @param descriptors the descriptions of the response payload's fields
+ * @return the snippet that will document the fields
+ * @see #fieldWithPath(String)
+ */
+ public static ResponseFieldsSnippet relaxedResponseFields(
+ Map
+ * If a parameter is present in the request path, but is not documented by one of the
+ * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+ * parameter is documented, is not marked as optional, and is not present in the
+ * request path, a failure will also occur.
+ *
+ * If you do not want to document a path parameter, a parameter descriptor can be
+ * marked as {@link ParameterDescriptor#ignored}. This will prevent it from appearing
+ * in the generated snippet while avoiding the failure described above.
+ *
+ * @param descriptors the descriptions of the parameters in the request's path
+ * @return the snippet that will document the parameters
+ */
+ public static PathParametersSnippet pathParameters(
+ List
+ * If a parameter is documented, is not marked as optional, and is not present in the
+ * response, a failure will occur. Any undocumented parameters will be ignored.
+ *
+ * @param descriptors the descriptions of the parameters in the request's path
+ * @return the snippet that will document the parameters
+ */
+ public static PathParametersSnippet relaxedPathParameters(
+ List
+ * If a parameter is present in the request path, but is not documented by one of the
+ * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+ * parameter is documented, is not marked as optional, and is not present in the
+ * request path, a failure will also occur.
+ *
+ * If you do not want to document a path parameter, a parameter descriptor can be
+ * marked as {@link ParameterDescriptor#ignored}. This will prevent it from appearing
+ * in the generated snippet while avoiding the failure described above.
+ *
+ * @param attributes the attributes
+ * @param descriptors the descriptions of the parameters in the request's path
+ * @return the snippet that will document the parameters
+ */
+ public static PathParametersSnippet pathParameters(Map
+ * If a parameter is documented, is not marked as optional, and is not present in the
+ * response, a failure will occur. Any undocumented parameters will be ignored.
+ *
+ * @param attributes the attributes
+ * @param descriptors the descriptions of the parameters in the request's path
+ * @return the snippet that will document the parameters
+ */
+ public static PathParametersSnippet relaxedPathParameters(
+ Map
+ * If a parameter is present in the request, but is not documented by one of the
+ * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+ * parameter is documented, is not marked as optional, and is not present in the
+ * request, a failure will also occur.
+ *
+ * If you do not want to document a request parameter, a parameter descriptor can be
+ * marked as {@link ParameterDescriptor#ignored}. This will prevent it from appearing
+ * in the generated snippet while avoiding the failure described above.
+ *
+ * @param descriptors The descriptions of the request's parameters
+ * @return the snippet
+ * @see OperationRequest#getParameters()
+ */
+ public static RequestParametersSnippet requestParameters(
+ List
+ * If a parameter is documented, is not marked as optional, and is not present in the
+ * response, a failure will occur. Any undocumented parameters will be ignored.
+ *
+ * @param descriptors The descriptions of the request's parameters
+ * @return the snippet
+ * @see OperationRequest#getParameters()
+ */
+ public static RequestParametersSnippet relaxedRequestParameters(
+ List
+ * If a parameter is present in the request, but is not documented by one of the
+ * descriptors, a failure will occur when the snippet is invoked. Similarly, if a
+ * parameter is documented, is not marked as optional, and is not present in the
+ * request, a failure will also occur.
+ *
+ * If you do not want to document a request parameter, a parameter descriptor can be
+ * marked as {@link ParameterDescriptor#ignored}. This will prevent it from appearing
+ * in the generated snippet while avoiding the failure described above.
+ *
+ * @param attributes the attributes
+ * @param descriptors the descriptions of the request's parameters
+ * @return the snippet that will document the parameters
+ * @see OperationRequest#getParameters()
+ */
+ public static RequestParametersSnippet requestParameters(
+ Map
+ * If a parameter is documented, is not marked as optional, and is not present in the
+ * response, a failure will occur. Any undocumented parameters will be ignored.
+ *
+ * @param attributes the attributes
+ * @param descriptors the descriptions of the request's parameters
+ * @return the snippet that will document the parameters
+ * @see OperationRequest#getParameters()
+ */
+ public static RequestParametersSnippet relaxedRequestParameters(
+ Map
+ * If a part is present in the request, but is not documented by one of the
+ * descriptors, a failure will occur when the snippet is invoked. Similarly, if a part
+ * is documented, is not marked as optional, and is not present in the request, a
+ * failure will also occur.
+ *
+ * If you do not want to document a part, a part descriptor can be marked as
+ * {@link RequestPartDescriptor#ignored}. This will prevent it from appearing in the
+ * generated snippet while avoiding the failure described above.
+ *
+ * @param descriptors The descriptions of the request's parts
+ * @return the snippet
+ * @see OperationRequest#getParts()
+ */
+ public static RequestPartsSnippet requestParts(List
+ * If a part is documented, is not marked as optional, and is not present in the
+ * request, a failure will occur. Any undocumented parts will be ignored.
+ *
+ * @param descriptors The descriptions of the request's parts
+ * @return the snippet
+ * @see OperationRequest#getParts()
+ */
+ public static RequestPartsSnippet relaxedRequestParts(
+ List
+ * If a part is present in the request, but is not documented by one of the
+ * descriptors, a failure will occur when the snippet is invoked. Similarly, if a part
+ * is documented, is not marked as optional, and is not present in the request, a
+ * failure will also occur.
+ *
+ * If you do not want to document a part, a part descriptor can be marked as
+ * {@link RequestPartDescriptor#ignored}. This will prevent it from appearing in the
+ * generated snippet while avoiding the failure described above.
+ *
+ * @param attributes the attributes
+ * @param descriptors the descriptions of the request's parts
+ * @return the snippet
+ * @see OperationRequest#getParts()
+ */
+ public static RequestPartsSnippet requestParts(Map
+ * If a part is documented, is not marked as optional, and is not present in the
+ * request, a failure will occur. Any undocumented parts will be ignored.
+ *
+ * @param attributes the attributes
+ * @param descriptors the descriptions of the request's parts
+ * @return the snippet
+ * @see OperationRequest#getParameters()
+ */
+ public static RequestPartsSnippet relaxedRequestParts(Map