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

Method Summary

Modifier and Type	Method and Description
static FieldDescriptor	fieldWithPath(String path) Creates a FieldDescriptor that describes a field with the given path.
static Snippet	requestFields(FieldDescriptor... descriptors) Returns a handler that will produce a snippet documenting the fields of the API call's request.
static Snippet	requestFields(Map<String,Object> attributes, FieldDescriptor... descriptors) Returns a handler that will produce a snippet documenting the fields of the API call's request.
static Snippet	responseFields(FieldDescriptor... descriptors) Returns a handler that will produce a snippet documenting the fields of the API call's response.
static Snippet	responseFields(Map<String,Object> attributes, FieldDescriptor... descriptors) Returns a handler that will produce a snippet documenting the fields of the API call's response.

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 Snippet requestFields(FieldDescriptor... descriptors)

Returns a handler that will produce a snippet documenting the fields of the API call's request.

If a field is present in the request, but is not documented by one of the descriptors, a failure will occur when the handler 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.

Parameters:

descriptors - The descriptions of the request's fields

Returns:

the handler

See Also:

fieldWithPath(String)

requestFields

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

Returns a handler that will produce a snippet documenting the fields of the API call's request. The given attributes will be available during snippet generation.

If a field is present in the request, but is not documented by one of the descriptors, a failure will occur when the handler 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.

Parameters:

attributes - Attributes made available during rendering of the snippet

descriptors - The descriptions of the request's fields

Returns:

the handler

See Also:

fieldWithPath(String)

responseFields

public static Snippet responseFields(FieldDescriptor... descriptors)

Returns a handler that will produce a snippet documenting the fields of the API call's response.

If a field is present in the response, but is not documented by one of the descriptors, a failure will occur when the handler is invoked. Similarly, if a field is documented, is not marked as optional, and is not present in the response, 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.

Parameters:

descriptors - The descriptions of the response's fields

Returns:

the handler

See Also:

fieldWithPath(String)

responseFields

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

Returns a handler that will produce a snippet documenting the fields of the API call's response. The given attributes will be available during snippet generation.

If a field is present in the response, but is not documented by one of the descriptors, a failure will occur when the handler is invoked. Similarly, if a field is documented, is not marked as optional, and is not present in the response, 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.

Parameters:

attributes - Attributes made available during rendering of the snippet

descriptors - The descriptions of the response's fields

Returns:

the handler

See Also:

fieldWithPath(String)