org.springframework.restdocs.payload

Class PayloadDocumentation

java.lang.Object

org.springframework.restdocs.payload.PayloadDocumentation

public abstract class PayloadDocumentation
extends Object

Static factory methods for documenting a RESTful API's request and response payloads.

Author:

Andreas Evers, Andy Wilkinson, Marcel Overdijk

Method Summary

Modifier and Type	Method and Description
static List<FieldDescriptor>	applyPathPrefix(String pathPrefix, List<FieldDescriptor> descriptors) Creates a copy of the given descriptors with the given pathPrefix applied to their paths.
static FieldDescriptor	fieldWithPath(String path) Creates a FieldDescriptor that describes a field with the given path.
static RequestFieldsSnippet	relaxedRequestFields(FieldDescriptor... descriptors) Returns a Snippet that will document the fields of the API operations's request payload.
static RequestFieldsSnippet	relaxedRequestFields(List<FieldDescriptor> descriptors) Returns a Snippet that will document the fields of the API operations's request payload.
static RequestFieldsSnippet	relaxedRequestFields(Map<String,Object> attributes, FieldDescriptor... descriptors) Returns a Snippet that will document the fields of the API operation's request payload.
static RequestFieldsSnippet	relaxedRequestFields(Map<String,Object> attributes, List<FieldDescriptor> descriptors) Returns a Snippet that will document the fields of the API operation's request payload.
static ResponseFieldsSnippet	relaxedResponseFields(FieldDescriptor... descriptors) Returns a Snippet that will document the fields of the API operation's response payload.
static ResponseFieldsSnippet	relaxedResponseFields(List<FieldDescriptor> descriptors) Returns a Snippet that will document the fields of the API operation's response payload.
static ResponseFieldsSnippet	relaxedResponseFields(Map<String,Object> attributes, FieldDescriptor... descriptors) Returns a Snippet that will document the fields of the API operation's response payload.
static ResponseFieldsSnippet	relaxedResponseFields(Map<String,Object> attributes, List<FieldDescriptor> descriptors) Returns a Snippet that will document the fields of the API operation's response payload.
static RequestFieldsSnippet	requestFields(FieldDescriptor... descriptors) Returns a Snippet that will document the fields of the API operations's request payload.
static RequestFieldsSnippet	requestFields(List<FieldDescriptor> descriptors) Returns a Snippet that will document the fields of the API operations's request payload.
static RequestFieldsSnippet	requestFields(Map<String,Object> attributes, FieldDescriptor... descriptors) Returns a Snippet that will document the fields of the API operation's request payload.
static RequestFieldsSnippet	requestFields(Map<String,Object> attributes, List<FieldDescriptor> descriptors) Returns a Snippet that will document the fields of the API operation's request payload.
static ResponseFieldsSnippet	responseFields(FieldDescriptor... descriptors) Returns a Snippet that will document the fields of the API operation's response payload.
static ResponseFieldsSnippet	responseFields(List<FieldDescriptor> descriptors) Returns a Snippet that will document the fields of the API operation's response payload.
static ResponseFieldsSnippet	responseFields(Map<String,Object> attributes, FieldDescriptor... descriptors) Returns a Snippet that will document the fields of the API operation's response payload.
static ResponseFieldsSnippet	responseFields(Map<String,Object> attributes, List<FieldDescriptor> descriptors) Returns a Snippet that will document the fields of the API operation's response payload.

Methods inherited from class java.lang.Object

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

Method Detail

fieldWithPath

public static FieldDescriptor fieldWithPath(String path)

Creates a FieldDescriptor that describes a field with the given path.

When documenting an XML payload, the path uses XPath, i.e. '/' is used to descend to a child node.

When documenting a JSON payload, the path uses '.' to descend into a child object and ' []' to descend into an array. For example, with this JSON payload:

 {
    "a":{
        "b":[
            {
                "c":"one"
            },
            {
                "c":"two"
            },
            {
                "d":"three"
            }
        ]
    }
 }
 

The following paths are all present:

Path	Value
a	An object containing "b"
a.b	An array containing three objects
a.b[]	An array containing three objects
a.b[].c	An array containing the strings "one" and "two"
a.b[].d	The string "three"

Parameters:

path - The path of the field

Returns:

a FieldDescriptor ready for further configuration

requestFields

public static RequestFieldsSnippet requestFields(FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of the API operations's request payload. The fields will be documented using the given descriptors.

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 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 payload's fields

Returns:

the snippet that will document the fields

See Also:

fieldWithPath(String)

requestFields

public static RequestFieldsSnippet requestFields(List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of the API operations's request payload. The fields will be documented using the given descriptors.

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 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 payload's fields

Returns:

the snippet that will document the fields

See Also:

fieldWithPath(String)

relaxedRequestFields

public static RequestFieldsSnippet relaxedRequestFields(FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of the API operations's request payload. The fields will be documented using the given descriptors.

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.

Parameters:

descriptors - the descriptions of the request payload's fields

Returns:

the snippet that will document the fields

See Also:

fieldWithPath(String)

relaxedRequestFields

public static RequestFieldsSnippet relaxedRequestFields(List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of the API operations's request payload. The fields will be documented using the given descriptors.

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.

Parameters:

descriptors - the descriptions of the request payload's fields

Returns:

the snippet that will document the fields

See Also:

fieldWithPath(String)

requestFields

public static RequestFieldsSnippet requestFields(Map<String,Object> attributes,
                                                 FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of the API operation's request payload. The fields will be documented using the given descriptors and the given attributes will be available during snippet generation.

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 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 payload's fields

Returns:

the snippet that will document the fields

See Also:

fieldWithPath(String)

requestFields

public static RequestFieldsSnippet requestFields(Map<String,Object> attributes,
                                                 List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of the API operation's request payload. The fields will be documented using the given descriptors and the given attributes will be available during snippet generation.

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 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 payload's fields

Returns:

the snippet that will document the fields

See Also:

fieldWithPath(String)

relaxedRequestFields

public static RequestFieldsSnippet relaxedRequestFields(Map<String,Object> attributes,
                                                        FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of the API operation's request payload. The fields will be documented using the given descriptors and the given attributes will be available during snippet generation.

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.

Parameters:

attributes - the attributes

descriptors - the descriptions of the request payload's fields

Returns:

the snippet that will document the fields

See Also:

fieldWithPath(String)

relaxedRequestFields

public static RequestFieldsSnippet relaxedRequestFields(Map<String,Object> attributes,
                                                        List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of the API operation's request payload. The fields will be documented using the given descriptors and the given attributes will be available during snippet generation.

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.

Parameters:

attributes - the attributes

descriptors - the descriptions of the request payload's fields

Returns:

the snippet that will document the fields

See Also:

fieldWithPath(String)

responseFields

public static ResponseFieldsSnippet responseFields(FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of the API operation's response payload. The fields will be documented using the given descriptors .

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

Parameters:

descriptors - the descriptions of the response payload's fields

Returns:

the snippet that will document the fields

See Also:

fieldWithPath(String)

responseFields

public static ResponseFieldsSnippet responseFields(List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of the API operation's response payload. The fields will be documented using the given descriptors .

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

Parameters:

descriptors - the descriptions of the response payload's fields

Returns:

the snippet that will document the fields

See Also:

fieldWithPath(String)

relaxedResponseFields

public static ResponseFieldsSnippet relaxedResponseFields(FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of the API operation's response payload. The fields will be documented using the given descriptors .

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.

Parameters:

descriptors - the descriptions of the response payload's fields

Returns:

the snippet that will document the fields

See Also:

fieldWithPath(String)

relaxedResponseFields

public static ResponseFieldsSnippet relaxedResponseFields(List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of the API operation's response payload. The fields will be documented using the given descriptors .

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.

Parameters:

descriptors - the descriptions of the response payload's fields

Returns:

the snippet that will document the fields

See Also:

fieldWithPath(String)

responseFields

public static ResponseFieldsSnippet responseFields(Map<String,Object> attributes,
                                                   FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of the API operation's response payload. The fields will be documented using the given descriptors and the given attributes will be available during snippet generation.

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 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 response payload's fields

Returns:

the snippet that will document the fields

See Also:

fieldWithPath(String)

responseFields

public static ResponseFieldsSnippet responseFields(Map<String,Object> attributes,
                                                   List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of the API operation's response payload. The fields will be documented using the given descriptors and the given attributes will be available during snippet generation.

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 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 response payload's fields

Returns:

the snippet that will document the fields

See Also:

fieldWithPath(String)

relaxedResponseFields

public static ResponseFieldsSnippet relaxedResponseFields(Map<String,Object> attributes,
                                                          FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of the API operation's response payload. The fields will be documented using the given descriptors and the given attributes will be available during snippet generation.

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.

Parameters:

attributes - the attributes

descriptors - the descriptions of the response payload's fields

Returns:

the snippet that will document the fields

See Also:

fieldWithPath(String)

relaxedResponseFields

public static ResponseFieldsSnippet relaxedResponseFields(Map<String,Object> attributes,
                                                          List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of the API operation's response payload. The fields will be documented using the given descriptors and the given attributes will be available during snippet generation.

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.

Parameters:

attributes - the attributes

descriptors - the descriptions of the response payload's fields

Returns:

the snippet that will document the fields

See Also:

fieldWithPath(String)

applyPathPrefix

public static List<FieldDescriptor> applyPathPrefix(String pathPrefix,
                                                    List<FieldDescriptor> descriptors)

Creates a copy of the given descriptors with the given pathPrefix applied to their paths.

Parameters:

pathPrefix - the path prefix

descriptors - the descriptors to copy

Returns:

the copied descriptors with the prefix applied