Package org.springframework.restdocs.request

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 Summary

Modifier and Type	Method	Description
static ParameterDescriptor	parameterWithName(String name)	Creates a ParameterDescriptor that describes a request or path parameter with the given name.
static RequestPartDescriptor	partWithName(String name)	Creates a RequestPartDescriptor that describes a request part with the given name.
static PathParametersSnippet	pathParameters(List<ParameterDescriptor> descriptors)	Returns a Snippet that will document the path parameters from the API operation's request.
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.
static PathParametersSnippet	pathParameters(Map<String,Object> attributes, ParameterDescriptor... descriptors)	Returns a Snippet that will document the path parameters from the API operation's request.
static PathParametersSnippet	pathParameters(ParameterDescriptor... descriptors)	Returns a Snippet that will document the path parameters from the API operation's request.
static PathParametersSnippet	relaxedPathParameters(List<ParameterDescriptor> descriptors)	Returns a Snippet that will document the path parameters from the API operation's request.
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.
static PathParametersSnippet	relaxedPathParameters(Map<String,Object> attributes, ParameterDescriptor... descriptors)	Returns a Snippet that will document the path parameters from the API operation's request.
static PathParametersSnippet	relaxedPathParameters(ParameterDescriptor... descriptors)	Returns a Snippet that will document the path parameters from the API operation's request.
static RequestParametersSnippet	relaxedRequestParameters(List<ParameterDescriptor> descriptors)	Returns a Snippet that will document the parameters from the API operation's request.
static RequestParametersSnippet	relaxedRequestParameters(Map<String,Object> attributes, List<ParameterDescriptor> descriptors)	Returns a Snippet that will document the parameters from the API operation's request.
static RequestParametersSnippet	relaxedRequestParameters(Map<String,Object> attributes, ParameterDescriptor... descriptors)	Returns a Snippet that will document the parameters from the API operation's request.
static RequestParametersSnippet	relaxedRequestParameters(ParameterDescriptor... descriptors)	Returns a Snippet that will document the parameters from the API operation's request.
static RequestPartsSnippet	relaxedRequestParts(List<RequestPartDescriptor> descriptors)	Returns a Snippet that will document the parts from the API operation's request.
static RequestPartsSnippet	relaxedRequestParts(Map<String,Object> attributes, List<RequestPartDescriptor> descriptors)	Returns a Snippet that will document the parts from the API operation's request.
static RequestPartsSnippet	relaxedRequestParts(Map<String,Object> attributes, RequestPartDescriptor... descriptors)	Returns a Snippet that will document the parts from the API operation's request.
static RequestPartsSnippet	relaxedRequestParts(RequestPartDescriptor... descriptors)	Returns a Snippet that will document the parts from the API operation's request.
static RequestParametersSnippet	requestParameters(List<ParameterDescriptor> descriptors)	Returns a Snippet that will document the parameters from the API operation's request.
static RequestParametersSnippet	requestParameters(Map<String,Object> attributes, List<ParameterDescriptor> descriptors)	Returns a Snippet that will document the parameters from the API operation's request.
static RequestParametersSnippet	requestParameters(Map<String,Object> attributes, ParameterDescriptor... descriptors)	Returns a Snippet that will document the parameters from the API operation's request.
static RequestParametersSnippet	requestParameters(ParameterDescriptor... descriptors)	Returns a Snippet that will document the parameters from the API operation's request.
static RequestPartsSnippet	requestParts(List<RequestPartDescriptor> descriptors)	Returns a Snippet that will document the parts from the API operation's request.
static RequestPartsSnippet	requestParts(Map<String,Object> attributes, List<RequestPartDescriptor> descriptors)	Returns a Snippet that will document the parts from the API operation's request.
static RequestPartsSnippet	requestParts(Map<String,Object> attributes, RequestPartDescriptor... descriptors)	Returns a Snippet that will document the parts from the API operation's request.
static RequestPartsSnippet	requestParts(RequestPartDescriptor... descriptors)	Returns a Snippet that will document the parts from the API operation's request.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

requestParameters

public static RequestParametersSnippet requestParameters(ParameterDescriptor... descriptors)

Returns a Snippet that will document the parameters from the API operation's request. The parameters will be documented using the given descriptors.

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 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 parameters

Returns:

the snippet

See Also:

• OperationRequest.getParameters()

requestParameters

public static RequestParametersSnippet requestParameters(List<ParameterDescriptor> descriptors)

Returns a Snippet that will document the parameters from the API operation's request. The parameters will be documented using the given descriptors.

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 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 parameters

Returns:

the snippet

See Also:

• OperationRequest.getParameters()

relaxedRequestParameters

public static RequestParametersSnippet relaxedRequestParameters(ParameterDescriptor... descriptors)

Returns a Snippet that will document the 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 request's parameters

Returns:

the snippet

See Also:

• OperationRequest.getParameters()

relaxedRequestParameters

public static RequestParametersSnippet relaxedRequestParameters(List<ParameterDescriptor> descriptors)

Returns a Snippet that will document the 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 request's parameters

Returns:

the snippet

See Also:

• OperationRequest.getParameters()

requestParameters

public static RequestParametersSnippet requestParameters(Map<String,Object> attributes,
 ParameterDescriptor... descriptors)

Returns a Snippet that will document the 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, 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 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 parameters

Returns:

the snippet that will document the parameters

See Also:

• OperationRequest.getParameters()

requestParameters

public static RequestParametersSnippet requestParameters(Map<String,Object> attributes,
 List<ParameterDescriptor> descriptors)

Returns a Snippet that will document the 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, 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 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 parameters

Returns:

the snippet that will document the parameters

See Also:

• OperationRequest.getParameters()

relaxedRequestParameters

public static RequestParametersSnippet relaxedRequestParameters(Map<String,Object> attributes,
 ParameterDescriptor... descriptors)

Returns a Snippet that will document the 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 request's parameters

Returns:

the snippet that will document the parameters

See Also:

• OperationRequest.getParameters()

relaxedRequestParameters

public static RequestParametersSnippet relaxedRequestParameters(Map<String,Object> attributes,
 List<ParameterDescriptor> descriptors)

Returns a Snippet that will document the 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 request's parameters

Returns:

the snippet that will document the parameters

See Also:

• OperationRequest.getParameters()

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:

• OperationRequest.getParts()

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:

• OperationRequest.getParts()

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:

• OperationRequest.getParts()

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:

• OperationRequest.getParts()

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:

• OperationRequest.getParts()

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:

• OperationRequest.getParts()

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

See Also:

• OperationRequest.getParameters()

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

See Also:

• OperationRequest.getParameters()