Class RequestDocumentation

java.lang.Object
org.springframework.restdocs.request.RequestDocumentation

public abstract class RequestDocumentation extends Object
Static factory methods for documenting aspects of a request sent to a RESTful API.
Author:
Andy Wilkinson, Marcel Overdijk
  • Method Details

    • parameterWithName

      public static ParameterDescriptor parameterWithName(String name)
      Creates a ParameterDescriptor that describes a request or path parameter with the given name.
      Parameters:
      name - the name of the parameter
      Returns:
      a ParameterDescriptor ready for further configuration
    • partWithName

      public static RequestPartDescriptor partWithName(String name)
      Creates a RequestPartDescriptor that describes a request part with the given name.
      Parameters:
      name - the name of the request part
      Returns:
      a RequestPartDescriptor ready for further configuration
    • pathParameters

      public static PathParametersSnippet pathParameters(ParameterDescriptor... descriptors)
      Returns a Snippet that will document the path parameters from the API operation's request. The parameters will be documented using the given descriptors.

      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 IgnorableDescriptor.ignored(). This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      Parameters:
      descriptors - the descriptions of the parameters in the request's path
      Returns:
      the snippet that will document the parameters
    • pathParameters

      public static PathParametersSnippet pathParameters(List<ParameterDescriptor> descriptors)
      Returns a Snippet that will document the path parameters from the API operation's request. The parameters will be documented using the given descriptors.

      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 IgnorableDescriptor.ignored(). This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      Parameters:
      descriptors - the descriptions of the parameters in the request's path
      Returns:
      the snippet that will document the parameters
    • relaxedPathParameters

      public static PathParametersSnippet relaxedPathParameters(ParameterDescriptor... descriptors)
      Returns a Snippet that will document the path parameters from the API operation's request. The parameters will be documented using the given descriptors.

      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.

      Parameters:
      descriptors - the descriptions of the parameters in the request's path
      Returns:
      the snippet that will document the parameters
    • relaxedPathParameters

      public static PathParametersSnippet relaxedPathParameters(List<ParameterDescriptor> descriptors)
      Returns a Snippet that will document the path parameters from the API operation's request. The parameters will be documented using the given descriptors.

      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.

      Parameters:
      descriptors - the descriptions of the parameters in the request's path
      Returns:
      the snippet that will document the parameters
    • pathParameters

      public static PathParametersSnippet pathParameters(Map<String,Object> attributes, ParameterDescriptor... descriptors)
      Returns a Snippet that will document the path parameters from the API operation's request. The given attributes will be available during snippet rendering and the parameters will be documented using the given descriptors .

      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 IgnorableDescriptor.ignored(). This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the parameters in the request's path
      Returns:
      the snippet that will document the parameters
    • pathParameters

      public static PathParametersSnippet pathParameters(Map<String,Object> attributes, List<ParameterDescriptor> descriptors)
      Returns a Snippet that will document the path parameters from the API operation's request. The given attributes will be available during snippet rendering and the parameters will be documented using the given descriptors .

      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 IgnorableDescriptor.ignored(). This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the parameters in the request's path
      Returns:
      the snippet that will document the parameters
    • relaxedPathParameters

      public static PathParametersSnippet relaxedPathParameters(Map<String,Object> attributes, ParameterDescriptor... descriptors)
      Returns a Snippet that will document the path parameters from the API operation's request. The given attributes will be available during snippet rendering and the parameters will be documented using the given descriptors .

      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.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the parameters in the request's path
      Returns:
      the snippet that will document the parameters
    • relaxedPathParameters

      public static PathParametersSnippet relaxedPathParameters(Map<String,Object> attributes, List<ParameterDescriptor> descriptors)
      Returns a Snippet that will document the path parameters from the API operation's request. The given attributes will be available during snippet rendering and the parameters will be documented using the given descriptors .

      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.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the parameters in the request's path
      Returns:
      the snippet that will document the parameters
    • queryParameters

      public static QueryParametersSnippet queryParameters(ParameterDescriptor... descriptors)
      Returns a Snippet that will document the query parameters from the API operation's request. The query parameters will be documented using the given descriptors.

      If a query 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 query 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 query parameter, a parameter descriptor can be marked as IgnorableDescriptor.ignored(). This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      Parameters:
      descriptors - the descriptions of the request's query parameters
      Returns:
      the snippet
      Since:
      3.0.0
    • queryParameters

      public static QueryParametersSnippet queryParameters(List<ParameterDescriptor> descriptors)
      Returns a Snippet that will document the query parameters from the API operation's request. The query parameters will be documented using the given descriptors.

      If a query 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 query 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 query parameter, a parameter descriptor can be marked as IgnorableDescriptor.ignored(). This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      Parameters:
      descriptors - the descriptions of the request's query parameters
      Returns:
      the snippet
      Since:
      3.0.0
    • relaxedQueryParameters

      public static QueryParametersSnippet relaxedQueryParameters(ParameterDescriptor... descriptors)
      Returns a Snippet that will document the query parameters from the API operation's request. The query parameters will be documented using the given descriptors.

      If a query parameter is documented, is not marked as optional, and is not present in the response, a failure will occur. Any undocumented query parameters will be ignored.

      Parameters:
      descriptors - the descriptions of the request's query parameters
      Returns:
      the snippet
      Since:
      3.0.0
    • relaxedQueryParameters

      public static QueryParametersSnippet relaxedQueryParameters(List<ParameterDescriptor> descriptors)
      Returns a Snippet that will document the query parameters from the API operation's request. The query parameters will be documented using the given descriptors.

      If a parameter is documented, is not marked as optional, and is not present in the response, a failure will occur. Any undocumented query parameters will be ignored.

      Parameters:
      descriptors - the descriptions of the request's query parameters
      Returns:
      the snippet
      Since:
      3.0.0
    • queryParameters

      public static QueryParametersSnippet queryParameters(Map<String,Object> attributes, ParameterDescriptor... descriptors)
      Returns a Snippet that will document the query parameters from the API operation's request. The given attributes will be available during snippet rendering and the query parameters will be documented using the given descriptors .

      If a query 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 query 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 query parameter, a parameter descriptor can be marked as IgnorableDescriptor.ignored(). This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the request's query parameters
      Returns:
      the snippet that will document the query parameters
      Since:
      3.0.0
    • queryParameters

      public static QueryParametersSnippet queryParameters(Map<String,Object> attributes, List<ParameterDescriptor> descriptors)
      Returns a Snippet that will document the query parameters from the API operation's request. The given attributes will be available during snippet rendering and the query parameters will be documented using the given descriptors .

      If a query 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 query 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 query parameter, a parameter descriptor can be marked as IgnorableDescriptor.ignored(). This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the request's query parameters
      Returns:
      the snippet that will document the query parameters
      Since:
      3.0.0
    • relaxedQueryParameters

      public static QueryParametersSnippet relaxedQueryParameters(Map<String,Object> attributes, ParameterDescriptor... descriptors)
      Returns a Snippet that will document the query parameters from the API operation's request. The given attributes will be available during snippet rendering and the query parameters will be documented using the given descriptors .

      If a query parameter is documented, is not marked as optional, and is not present in the response, a failure will occur. Any undocumented query parameters will be ignored.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the request's query parameters
      Returns:
      the snippet that will document the query parameters
      Since:
      3.0.0
    • relaxedQueryParameters

      public static QueryParametersSnippet relaxedQueryParameters(Map<String,Object> attributes, List<ParameterDescriptor> descriptors)
      Returns a Snippet that will document the query parameters from the API operation's request. The given attributes will be available during snippet rendering and the query parameters will be documented using the given descriptors .

      If a query parameter is documented, is not marked as optional, and is not present in the response, a failure will occur. Any undocumented query parameters will be ignored.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the request's query parameters
      Returns:
      the snippet that will document the query parameters
      Since:
      3.0.0
    • formParameters

      public static FormParametersSnippet formParameters(ParameterDescriptor... descriptors)
      Returns a Snippet that will document the form parameters from the API operation's request. The form parameters will be documented using the given descriptors.

      If a form 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 form 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 form parameter, a parameter descriptor can be marked as IgnorableDescriptor.ignored(). This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      Parameters:
      descriptors - the descriptions of the request's form parameters
      Returns:
      the snippet
      Since:
      3.0.0
    • formParameters

      public static FormParametersSnippet formParameters(List<ParameterDescriptor> descriptors)
      Returns a Snippet that will document the form parameters from the API operation's request. The form parameters will be documented using the given descriptors.

      If a form 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 form 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 form parameter, a parameter descriptor can be marked as IgnorableDescriptor.ignored(). This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      Parameters:
      descriptors - the descriptions of the request's form parameters
      Returns:
      the snippet
      Since:
      3.0.0
    • relaxedFormParameters

      public static FormParametersSnippet relaxedFormParameters(ParameterDescriptor... descriptors)
      Returns a Snippet that will document the form parameters from the API operation's request. The form parameters will be documented using the given descriptors.

      If a form parameter is documented, is not marked as optional, and is not present in the response, a failure will occur. Any undocumented form parameters will be ignored.

      Parameters:
      descriptors - the descriptions of the request's form parameters
      Returns:
      the snippet
      Since:
      3.0.0
    • relaxedFormParameters

      public static FormParametersSnippet relaxedFormParameters(List<ParameterDescriptor> descriptors)
      Returns a Snippet that will document the form parameters from the API operation's request. The form parameters will be documented using the given descriptors.

      If a parameter is documented, is not marked as optional, and is not present in the response, a failure will occur. Any undocumented form parameters will be ignored.

      Parameters:
      descriptors - the descriptions of the request's form parameters
      Returns:
      the snippet
      Since:
      3.0.0
    • formParameters

      public static FormParametersSnippet formParameters(Map<String,Object> attributes, ParameterDescriptor... descriptors)
      Returns a Snippet that will document the form parameters from the API operation's request. The given attributes will be available during snippet rendering and the form parameters will be documented using the given descriptors .

      If a form 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 form 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 form parameter, a parameter descriptor can be marked as IgnorableDescriptor.ignored(). This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the request's form parameters
      Returns:
      the snippet that will document the form parameters
      Since:
      3.0.0
    • formParameters

      public static FormParametersSnippet formParameters(Map<String,Object> attributes, List<ParameterDescriptor> descriptors)
      Returns a Snippet that will document the form parameters from the API operation's request. The given attributes will be available during snippet rendering and the form parameters will be documented using the given descriptors .

      If a form 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 form 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 form parameter, a parameter descriptor can be marked as IgnorableDescriptor.ignored(). This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the request's form parameters
      Returns:
      the snippet that will document the form parameters
      Since:
      3.0.0
    • relaxedFormParameters

      public static FormParametersSnippet relaxedFormParameters(Map<String,Object> attributes, ParameterDescriptor... descriptors)
      Returns a Snippet that will document the form parameters from the API operation's request. The given attributes will be available during snippet rendering and the form parameters will be documented using the given descriptors .

      If a form parameter is documented, is not marked as optional, and is not present in the response, a failure will occur. Any undocumented form parameters will be ignored.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the request's form parameters
      Returns:
      the snippet that will document the form parameters
      Since:
      3.0.0
    • relaxedFormParameters

      public static FormParametersSnippet relaxedFormParameters(Map<String,Object> attributes, List<ParameterDescriptor> descriptors)
      Returns a Snippet that will document the form parameters from the API operation's request. The given attributes will be available during snippet rendering and the form parameters will be documented using the given descriptors .

      If a form parameter is documented, is not marked as optional, and is not present in the response, a failure will occur. Any undocumented form parameters will be ignored.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the request's form parameters
      Returns:
      the snippet that will document the form parameters
      Since:
      3.0.0
    • requestParts

      public static RequestPartsSnippet requestParts(RequestPartDescriptor... descriptors)
      Returns a Snippet that will document the parts from the API operation's request. The parts will be documented using the given descriptors.

      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 IgnorableDescriptor.ignored(). This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      Parameters:
      descriptors - the descriptions of the request's parts
      Returns:
      the snippet
      See Also:
    • requestParts

      public static RequestPartsSnippet requestParts(List<RequestPartDescriptor> descriptors)
      Returns a Snippet that will document the parts from the API operation's request. The parts will be documented using the given descriptors.

      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 IgnorableDescriptor.ignored(). This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      Parameters:
      descriptors - the descriptions of the request's parts
      Returns:
      the snippet
      See Also:
    • relaxedRequestParts

      public static RequestPartsSnippet relaxedRequestParts(RequestPartDescriptor... descriptors)
      Returns a Snippet that will document the parts from the API operation's request. The parameters will be documented using the given descriptors.

      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.

      Parameters:
      descriptors - the descriptions of the request's parts
      Returns:
      the snippet
      See Also:
    • relaxedRequestParts

      public static RequestPartsSnippet relaxedRequestParts(List<RequestPartDescriptor> descriptors)
      Returns a Snippet that will document the parts from the API operation's request. The parameters will be documented using the given descriptors.

      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.

      Parameters:
      descriptors - the descriptions of the request's parts
      Returns:
      the snippet
      See Also:
    • requestParts

      public static RequestPartsSnippet requestParts(Map<String,Object> attributes, RequestPartDescriptor... descriptors)
      Returns a Snippet that will document the parts from the API operation's request. The given attributes will be available during snippet rendering and the parts will be documented using the given descriptors.

      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 IgnorableDescriptor.ignored(). This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the request's parts
      Returns:
      the snippet
      See Also:
    • requestParts

      public static RequestPartsSnippet requestParts(Map<String,Object> attributes, List<RequestPartDescriptor> descriptors)
      Returns a Snippet that will document the parts from the API operation's request. The given attributes will be available during snippet rendering and the parts will be documented using the given descriptors.

      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 IgnorableDescriptor.ignored(). This will prevent it from appearing in the generated snippet while avoiding the failure described above.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the request's parts
      Returns:
      the snippet
      See Also:
    • relaxedRequestParts

      public static RequestPartsSnippet relaxedRequestParts(Map<String,Object> attributes, RequestPartDescriptor... descriptors)
      Returns a Snippet that will document the parts from the API operation's request. The given attributes will be available during snippet rendering and the parts will be documented using the given descriptors.

      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.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the request's parts
      Returns:
      the snippet
    • relaxedRequestParts

      public static RequestPartsSnippet relaxedRequestParts(Map<String,Object> attributes, List<RequestPartDescriptor> descriptors)
      Returns a Snippet that will document the parts from the API operation's request. The given attributes will be available during snippet rendering and the parts will be documented using the given descriptors.

      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.

      Parameters:
      attributes - the attributes
      descriptors - the descriptions of the request's parts
      Returns:
      the snippet