Package 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	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 PayloadSubsectionExtractor<?>	beneathPath(String path)	Returns a PayloadSubsectionExtractor that will extract the subsection of the JSON payload found beneath the given path.
static FieldDescriptor	fieldWithPath(String path)	Creates a FieldDescriptor that describes a field with the given path.
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, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields of the API operation'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(FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of the API operations's request payload.
static RequestFieldsSnippet	relaxedRequestFields(PayloadSubsectionExtractor<?> subsectionExtractor, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields of the subsection of the API operations's request payload extracted by the given subsectionExtractor .
static RequestFieldsSnippet	relaxedRequestFields(PayloadSubsectionExtractor<?> subsectionExtractor, Map<String,Object> attributes, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields of the subsection of the API operation's request payload extracted by the given subsectionExtractor.
static RequestFieldsSnippet	relaxedRequestFields(PayloadSubsectionExtractor<?> subsectionExtractor, Map<String,Object> attributes, FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of the subsection of the API operation's request payload extracted by the given subsectionExtractor.
static RequestFieldsSnippet	relaxedRequestFields(PayloadSubsectionExtractor<?> subsectionExtractor, FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of the subsection of the API operations's request payload extracted by the given subsectionExtractor .
static RequestPartFieldsSnippet	relaxedRequestPartFields(String part, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields of the specified part of the API operations's request payload.
static RequestPartFieldsSnippet	relaxedRequestPartFields(String part, Map<String,Object> attributes, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields of the specified part of the API operations's request payload.
static RequestPartFieldsSnippet	relaxedRequestPartFields(String part, Map<String,Object> attributes, FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of the specified part of the API operations's request payload.
static RequestPartFieldsSnippet	relaxedRequestPartFields(String part, FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of the specified part of the API operations's request payload.
static RequestPartFieldsSnippet	relaxedRequestPartFields(String part, PayloadSubsectionExtractor<?> subsectionExtractor, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields of a subsection of the specified part of the API operations's request payload.
static RequestPartFieldsSnippet	relaxedRequestPartFields(String part, PayloadSubsectionExtractor<?> subsectionExtractor, Map<String,Object> attributes, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields of a subsection of the specified part of the API operations's request payload.
static RequestPartFieldsSnippet	relaxedRequestPartFields(String part, PayloadSubsectionExtractor<?> subsectionExtractor, Map<String,Object> attributes, FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of a subsection of the specified part of the API operations's request payload.
static RequestPartFieldsSnippet	relaxedRequestPartFields(String part, PayloadSubsectionExtractor<?> subsectionExtractor, FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of a subsection of the specified part of the API operations's request 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, 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(FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of the API operation's response payload.
static ResponseFieldsSnippet	relaxedResponseFields(PayloadSubsectionExtractor<?> subsectionExtractor, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields of a subsection of the API operation's response payload.
static ResponseFieldsSnippet	relaxedResponseFields(PayloadSubsectionExtractor<?> subsectionExtractor, Map<String,Object> attributes, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields of a subsection of the API operation's response payload.
static ResponseFieldsSnippet	relaxedResponseFields(PayloadSubsectionExtractor<?> subsectionExtractor, Map<String,Object> attributes, FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of a subsection of the API operation's response payload.
static ResponseFieldsSnippet	relaxedResponseFields(PayloadSubsectionExtractor<?> subsectionExtractor, FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of a subsection of the API operation's response payload.
static RequestBodySnippet	requestBody()	Returns a Snippet that will document the body of the API operation's request payload.
static RequestBodySnippet	requestBody(Map<String,Object> attributes)	Returns a Snippet that will document the body of the API operation's request payload.
static RequestBodySnippet	requestBody(PayloadSubsectionExtractor<?> subsectionExtractor)	Returns a Snippet that will document a subsection of the body of the API operation's request payload.
static RequestBodySnippet	requestBody(PayloadSubsectionExtractor<?> subsectionExtractor, Map<String,Object> attributes)	Returns a Snippet that will document a subsection of the body of the API operation'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, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields of the API operation'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(FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of the API operations's request payload.
static RequestFieldsSnippet	requestFields(PayloadSubsectionExtractor<?> subsectionExtractor, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields in the subsection of the API operations's request payload extracted by the given subsectionExtractor .
static RequestFieldsSnippet	requestFields(PayloadSubsectionExtractor<?> subsectionExtractor, Map<String,Object> attributes, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields of the subsection of the API operation's request payload extracted by the given subsectionExtractor.
static RequestFieldsSnippet	requestFields(PayloadSubsectionExtractor<?> subsectionExtractor, Map<String,Object> attributes, FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of the subsection of the API operation's request payload extracted by the given subsectionExtractor.
static RequestFieldsSnippet	requestFields(PayloadSubsectionExtractor<?> subsectionExtractor, FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of the subsection of API operations's request payload extracted by the given subsectionExtractor.
static RequestPartBodySnippet	requestPartBody(String partName)	Returns a Snippet that will document the body of specified part of the API operation's request payload.
static RequestPartBodySnippet	requestPartBody(String partName, Map<String,Object> attributes)	Returns a Snippet that will document the body of specified part of the API operation's request payload.
static RequestPartBodySnippet	requestPartBody(String partName, PayloadSubsectionExtractor<?> subsectionExtractor)	Returns a Snippet that will document a subsection of the body of specified part of the API operation's request payload.
static RequestPartBodySnippet	requestPartBody(String partName, PayloadSubsectionExtractor<?> subsectionExtractor, Map<String,Object> attributes)	Returns a Snippet that will document a subsection of the body of specified part of the API operation's request payload.
static RequestPartFieldsSnippet	requestPartFields(String part, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields of the specified part of the API operations's request payload.
static RequestPartFieldsSnippet	requestPartFields(String part, Map<String,Object> attributes, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields of the specified part of the API operations's request payload.
static RequestPartFieldsSnippet	requestPartFields(String part, Map<String,Object> attributes, FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of the specified part of the API operations's request payload.
static RequestPartFieldsSnippet	requestPartFields(String part, FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of the specified part of the API operations's request payload.
static RequestPartFieldsSnippet	requestPartFields(String part, PayloadSubsectionExtractor<?> subsectionExtractor, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields of a subsection of the specified part of the API operations's request payload.
static RequestPartFieldsSnippet	requestPartFields(String part, PayloadSubsectionExtractor<?> subsectionExtractor, Map<String,Object> attributes, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields of a subsection of the specified part of the API operations's request payload.
static RequestPartFieldsSnippet	requestPartFields(String part, PayloadSubsectionExtractor<?> subsectionExtractor, Map<String,Object> attributes, FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of a subsection of the specified part of the API operations's request payload.
static RequestPartFieldsSnippet	requestPartFields(String part, PayloadSubsectionExtractor<?> subsectionExtractor, FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of a subsection of the specified part of the API operations's request payload.
static ResponseBodySnippet	responseBody()	Returns a Snippet that will document the body of the API operation's response payload.
static ResponseBodySnippet	responseBody(Map<String,Object> attributes)	Returns a Snippet that will document the body of the API operation's response payload.
static ResponseBodySnippet	responseBody(PayloadSubsectionExtractor<?> subsectionExtractor)	Returns a Snippet that will document a subsection of the body of the API operation's response payload.
static ResponseBodySnippet	responseBody(PayloadSubsectionExtractor<?> subsectionExtractor, Map<String,Object> attributes)	Returns a Snippet that will document a subsection of the body 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, 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(FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of the API operation's response payload.
static ResponseFieldsSnippet	responseFields(PayloadSubsectionExtractor<?> subsectionExtractor, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields of a subsection of the API operation's response payload.
static ResponseFieldsSnippet	responseFields(PayloadSubsectionExtractor<?> subsectionExtractor, Map<String,Object> attributes, List<FieldDescriptor> descriptors)	Returns a Snippet that will document the fields of a subsection of the API operation's response payload.
static ResponseFieldsSnippet	responseFields(PayloadSubsectionExtractor<?> subsectionExtractor, Map<String,Object> attributes, FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of a subsection of the API operation's response payload.
static ResponseFieldsSnippet	responseFields(PayloadSubsectionExtractor<?> subsectionExtractor, FieldDescriptor... descriptors)	Returns a Snippet that will document the fields of a subsection of the API operation's response payload.
static SubsectionDescriptor	subsectionWithPath(String path)	Creates a FieldDescriptor that describes a subsection, i.e.

Methods inherited from class java.lang.Object

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

Method Details

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:

Paths that are present and their values

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

subsectionWithPath

public static SubsectionDescriptor subsectionWithPath(String path)

Creates a FieldDescriptor that describes a subsection, i.e. a field and all of its descendants, 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:

Paths that are present and their values

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"

A subsection descriptor for the array with the path a.b[] will also describe its descendants a.b[].c and a.b[].d.

Parameters:

path - the path of the subsection

Returns:

a SubsectionDescriptor 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 with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

descriptors - the descriptions of the request payload's fields

Returns:

the snippet that will document the fields

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• AbstractDescriptor.description(Object)

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 with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

descriptors - the descriptions of the request payload's fields

Returns:

the snippet that will document the fields

See Also:

• fieldWithPath(String)
• subsectionWithPath(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)
• subsectionWithPath(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)
• subsectionWithPath(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, a failure will also occur. For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

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)
• subsectionWithPath(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, a failure will also occur. For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

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)
• subsectionWithPath(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)
• subsectionWithPath(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)
• subsectionWithPath(String)

requestFields

public static RequestFieldsSnippet requestFields(PayloadSubsectionExtractor<?> subsectionExtractor,
 FieldDescriptor... descriptors)

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

If a field is present in the subsection of 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 subsection, a failure will also occur.For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

subsectionExtractor - the subsection extractor

descriptors - the descriptions of the request payload's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

requestFields

public static RequestFieldsSnippet requestFields(PayloadSubsectionExtractor<?> subsectionExtractor,
 List<FieldDescriptor> descriptors)

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

If a field is present in the subsection of 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 subsection, a failure will also occur. For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

subsectionExtractor - the subsection extractor

descriptors - the descriptions of the request payload's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

relaxedRequestFields

public static RequestFieldsSnippet relaxedRequestFields(PayloadSubsectionExtractor<?> subsectionExtractor,
 FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of the subsection of the API operations's request payload extracted by the given subsectionExtractor . 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:

subsectionExtractor - the subsection extractor

descriptors - the descriptions of the request payload's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

relaxedRequestFields

public static RequestFieldsSnippet relaxedRequestFields(PayloadSubsectionExtractor<?> subsectionExtractor,
 List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of the subsection of the API operations's request payload extracted by the given subsectionExtractor . 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:

subsectionExtractor - the subsection extractor

descriptors - the descriptions of the request payload's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

requestFields

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

Returns a Snippet that will document the fields of the subsection of the API operation's request payload extracted by the given subsectionExtractor. 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 subsection of 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 subsection, a failure will also occur. For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

subsectionExtractor - the subsection extractor

attributes - the attributes

descriptors - the descriptions of the request payload's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

requestFields

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

Returns a Snippet that will document the fields of the subsection of the API operation's request payload extracted by the given subsectionExtractor. 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 subsection of 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 subsection, a failure will also occur. For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

subsectionExtractor - the subsection extractor

attributes - the attributes

descriptors - the descriptions of the request payload's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

relaxedRequestFields

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

Returns a Snippet that will document the fields of the subsection of the API operation's request payload extracted by the given subsectionExtractor. 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:

subsectionExtractor - the subsection extractor

attributes - the attributes

descriptors - the descriptions of the request payload's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

relaxedRequestFields

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

Returns a Snippet that will document the fields of the subsection of the API operation's request payload extracted by the given subsectionExtractor. 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:

subsectionExtractor - the subsection extractor

attributes - the attributes

descriptors - the descriptions of the request payload's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

requestPartFields

public static RequestPartFieldsSnippet requestPartFields(String part,
 FieldDescriptor... descriptors)

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

If a field is present in the payload of the request part, 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 part's payload, a failure will also occur. For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

part - the part name

descriptors - the descriptions of the request part's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)

requestPartFields

public static RequestPartFieldsSnippet requestPartFields(String part,
 List<FieldDescriptor> descriptors)

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

If a field is present in the payload of the request part, 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 part's payload, a failure will also occur. For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

part - the part name

descriptors - the descriptions of the request part's fields

Returns:

the snippet that will document the fields

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)

relaxedRequestPartFields

public static RequestPartFieldsSnippet relaxedRequestPartFields(String part,
 FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of the specified part 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:

part - the part name

descriptors - the descriptions of the request part's fields

Returns:

the snippet that will document the fields

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)

relaxedRequestPartFields

public static RequestPartFieldsSnippet relaxedRequestPartFields(String part,
 List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of the specified part 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:

part - the part name

descriptors - the descriptions of the request part's fields

Returns:

the snippet that will document the fields

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)

requestPartFields

public static RequestPartFieldsSnippet requestPartFields(String part,
 Map<String,Object> attributes,
 FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of the specified part of the API operations'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 payload of the request part, 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 part's payload, a failure will also occur. For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

part - the part name

attributes - the attributes

descriptors - the descriptions of the request part's fields

Returns:

the snippet that will document the fields

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)

requestPartFields

public static RequestPartFieldsSnippet requestPartFields(String part,
 Map<String,Object> attributes,
 List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of the specified part of the API operations'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 payload of the request part, 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 part's payload, a failure will also occur. For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

part - the part name

attributes - the attributes

descriptors - the descriptions of the request part's fields

Returns:

the snippet that will document the fields

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)

relaxedRequestPartFields

public static RequestPartFieldsSnippet relaxedRequestPartFields(String part,
 Map<String,Object> attributes,
 FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of the specified part of the API operations'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:

part - the part name

attributes - the attributes

descriptors - the descriptions of the request part's fields

Returns:

the snippet that will document the fields

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)

relaxedRequestPartFields

public static RequestPartFieldsSnippet relaxedRequestPartFields(String part,
 Map<String,Object> attributes,
 List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of the specified part of the API operations'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:

part - the part name

attributes - the attributes

descriptors - the descriptions of the request part's fields

Returns:

the snippet that will document the fields

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)

requestPartFields

public static RequestPartFieldsSnippet requestPartFields(String part,
 PayloadSubsectionExtractor<?> subsectionExtractor,
 FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of a subsection of the specified part of the API operations's request payload. The subsection will be extracted by the given subsectionExtractor. The fields will be documented using the given descriptors.

If a field is present in the subsection of the request part 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 subsection, a failure will also occur. For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

part - the part name

subsectionExtractor - the subsection extractor

descriptors - the descriptions of the subsection's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

requestPartFields

public static RequestPartFieldsSnippet requestPartFields(String part,
 PayloadSubsectionExtractor<?> subsectionExtractor,
 List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of a subsection of the specified part of the API operations's request payload. The subsection will be extracted by the given subsectionExtractor. The fields will be documented using the given descriptors.

If a field is present in the subsection of the request part 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 subsection, a failure will also occur. For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

part - the part name

subsectionExtractor - the subsection extractor

descriptors - the descriptions of the subsection's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

relaxedRequestPartFields

public static RequestPartFieldsSnippet relaxedRequestPartFields(String part,
 PayloadSubsectionExtractor<?> subsectionExtractor,
 FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of a subsection of the specified part of the API operations's request payload. The subsection will be extracted by the given subsectionExtractor. 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:

part - the part name

subsectionExtractor - the subsection extractor

descriptors - the descriptions of the request part's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

relaxedRequestPartFields

public static RequestPartFieldsSnippet relaxedRequestPartFields(String part,
 PayloadSubsectionExtractor<?> subsectionExtractor,
 List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of a subsection of the specified part of the API operations's request payload. The subsection will be extracted by the given subsectionExtractor. 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:

part - the part name

subsectionExtractor - the subsection extractor

descriptors - the descriptions of the request part's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

requestPartFields

public static RequestPartFieldsSnippet requestPartFields(String part,
 PayloadSubsectionExtractor<?> subsectionExtractor,
 Map<String,Object> attributes,
 FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of a subsection of the specified part of the API operations's request payload. The subsection will be extracted by the givne subsectionExtractor. 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 subsection of the request part 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 subsection, a failure will also occur. For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

part - the part name

subsectionExtractor - the subsection extractor

attributes - the attributes

descriptors - the descriptions of the request part's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

requestPartFields

public static RequestPartFieldsSnippet requestPartFields(String part,
 PayloadSubsectionExtractor<?> subsectionExtractor,
 Map<String,Object> attributes,
 List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of a subsection of the specified part of the API operations's request payload. The subsection will be extracted by the given subsectionExtractor. 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 subsection of the request part 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 subsection, a failure will also occur. For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

part - the part name

subsectionExtractor - the subsection extractor

attributes - the attributes

descriptors - the descriptions of the request part's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

relaxedRequestPartFields

public static RequestPartFieldsSnippet relaxedRequestPartFields(String part,
 PayloadSubsectionExtractor<?> subsectionExtractor,
 Map<String,Object> attributes,
 FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of a subsection of the specified part of the API operations's request payload. The subsection will be extracted by the given subsectionExtractor. 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:

part - the part name

subsectionExtractor - the subsection extractor

attributes - the attributes

descriptors - the descriptions of the request part's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

relaxedRequestPartFields

public static RequestPartFieldsSnippet relaxedRequestPartFields(String part,
 PayloadSubsectionExtractor<?> subsectionExtractor,
 Map<String,Object> attributes,
 List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of a subsection of the specified part of the API operations's request payload. The subsection will be extracted by the given subsectionExtractor. 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:

part - the part name

subsectionExtractor - the subsection extractor

attributes - the attributes

descriptors - the descriptions of the request part's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(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, a failure will also occur. For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

descriptors - the descriptions of the response payload's fields

Returns:

the snippet that will document the fields

See Also:

• fieldWithPath(String)
• subsectionWithPath(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, a failure will also occur. For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

descriptors - the descriptions of the response payload's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(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

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(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)
• subsectionWithPath(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, a failure will also occur. For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

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)
• subsectionWithPath(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, a failure will also occur. For payloads with a hierarchical structure, documenting a field with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

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)
• subsectionWithPath(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)
• subsectionWithPath(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)
• subsectionWithPath(String)

responseFields

public static ResponseFieldsSnippet responseFields(PayloadSubsectionExtractor<?> subsectionExtractor,
 FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of a subsection of the API operation's response payload. The subsection will be extracted using the given subsectionExtractor. 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 with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

subsectionExtractor - the subsection extractor

descriptors - the descriptions of the response payload's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

responseFields

public static ResponseFieldsSnippet responseFields(PayloadSubsectionExtractor<?> subsectionExtractor,
 List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of a subsection of the API operation's response payload. The subsection will be extracted using the given subsectionExtractor. 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 with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

subsectionExtractor - the subsection extractor

descriptors - the descriptions of the response payload's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

relaxedResponseFields

public static ResponseFieldsSnippet relaxedResponseFields(PayloadSubsectionExtractor<?> subsectionExtractor,
 FieldDescriptor... descriptors)

Returns a Snippet that will document the fields of a subsection of the API operation's response payload. The subsection will be extracted using the given subsectionExtractor. 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:

subsectionExtractor - the subsection extractor

descriptors - the descriptions of the response payload's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

relaxedResponseFields

public static ResponseFieldsSnippet relaxedResponseFields(PayloadSubsectionExtractor<?> subsectionExtractor,
 List<FieldDescriptor> descriptors)

Returns a Snippet that will document the fields of a subsection of the API operation's response payload. The subsection will be extracted using the given subsectionExtractor. 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:

subsectionExtractor - the subsection extractor

descriptors - the descriptions of the response payload's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

responseFields

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

Returns a Snippet that will document the fields of a subsection of the API operation's response payload. The subsection will be extracted using the given subsectionExtractor. 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 with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

subsectionExtractor - the subsection extractor

attributes - the attributes

descriptors - the descriptions of the response payload's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

responseFields

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

Returns a Snippet that will document the fields of a subsection of the API operation's response payload. The subsection will be extracted using the given subsectionExtractor. 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 with a subsection descriptor will mean that all of its descendants are also treated as having been documented.

If you do not want to document a field or subsection, a descriptor can be configured to ignore it. The ignored field or subsection will not appear in the generated snippet and the failure described above will not occur.

Parameters:

subsectionExtractor - the subsection extractor

attributes - the attributes

descriptors - the descriptions of the response payload's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

relaxedResponseFields

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

Returns a Snippet that will document the fields of a subsection of the API operation's response payload. The subsection will be extracted using the given subsectionExtractor. 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:

subsectionExtractor - the subsection extractor

attributes - the attributes

descriptors - the descriptions of the response payload's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

relaxedResponseFields

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

Returns a Snippet that will document the fields of a subsection of the API operation's response payload. The subsection will be extracted using the given subsectionExtractor. 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:

subsectionExtractor - the subsection extractor

attributes - the attributes

descriptors - the descriptions of the response payload's fields

Returns:

the snippet that will document the fields

Since:

1.2.0

See Also:

• fieldWithPath(String)
• subsectionWithPath(String)
• beneathPath(String)

requestBody

public static RequestBodySnippet requestBody()

Returns a Snippet that will document the body of the API operation's request payload.

Returns:

the snippet that will document the request body

requestBody

public static RequestBodySnippet requestBody(Map<String,Object> attributes)

Returns a Snippet that will document the body of the API operation's request payload. The given attributes will be made available during snippet generation.

Parameters:

attributes - the attributes

Returns:

the snippet that will document the request body

requestBody

public static RequestBodySnippet requestBody(PayloadSubsectionExtractor<?> subsectionExtractor)

Returns a Snippet that will document a subsection of the body of the API operation's request payload. The subsection will be extracted using the given subsectionExtractor.

Parameters:

subsectionExtractor - the subsection extractor

Returns:

the snippet that will document the request body subsection

requestBody

public static RequestBodySnippet requestBody(PayloadSubsectionExtractor<?> subsectionExtractor,
 Map<String,Object> attributes)

Returns a Snippet that will document a subsection of the body of the API operation's request payload. The subsection will be extracted using the given subsectionExtractor. The given attributes will be made available during snippet generation.

Parameters:

subsectionExtractor - the subsection extractor

attributes - the attributes

Returns:

the snippet that will document the request body subsection

responseBody

public static ResponseBodySnippet responseBody()

Returns a Snippet that will document the body of the API operation's response payload.

Returns:

the snippet that will document the response body

responseBody

public static ResponseBodySnippet responseBody(Map<String,Object> attributes)

Returns a Snippet that will document the body of the API operation's response payload. The given attributes will be made available during snippet generation.

Parameters:

attributes - the attributes

Returns:

the snippet that will document the response body

responseBody

public static ResponseBodySnippet responseBody(PayloadSubsectionExtractor<?> subsectionExtractor)

Returns a Snippet that will document a subsection of the body of the API operation's response payload. The subsection will be extracted using the given subsectionExtractor.

Parameters:

subsectionExtractor - the subsection extractor

Returns:

the snippet that will document the response body subsection

responseBody

public static ResponseBodySnippet responseBody(PayloadSubsectionExtractor<?> subsectionExtractor,
 Map<String,Object> attributes)

Returns a Snippet that will document a subsection of the body of the API operation's response payload. The subsection will be extracted using the given subsectionExtractor. The given attributes will be made available during snippet generation.

Parameters:

subsectionExtractor - the subsection extractor

attributes - the attributes

Returns:

the snippet that will document the response body subsection

requestPartBody

public static RequestPartBodySnippet requestPartBody(String partName)

Returns a Snippet that will document the body of specified part of the API operation's request payload.

Parameters:

partName - the name of the request part

Returns:

the snippet that will document the response body

requestPartBody

public static RequestPartBodySnippet requestPartBody(String partName,
 Map<String,Object> attributes)

Returns a Snippet that will document the body of specified part of the API operation's request payload. The given attributes will be made available during snippet generation.

Parameters:

partName - the name of the request part

attributes - the attributes

Returns:

the snippet that will document the response body

requestPartBody

public static RequestPartBodySnippet requestPartBody(String partName,
 PayloadSubsectionExtractor<?> subsectionExtractor)

Returns a Snippet that will document a subsection of the body of specified part of the API operation's request payload. The subsection will be extracted using the given subsectionExtractor.

Parameters:

partName - the name of the request part

subsectionExtractor - the subsection extractor

Returns:

the snippet that will document the response body

requestPartBody

public static RequestPartBodySnippet requestPartBody(String partName,
 PayloadSubsectionExtractor<?> subsectionExtractor,
 Map<String,Object> attributes)

Returns a Snippet that will document a subsection of the body of specified part of the API operation's request payload. The subsection will be extracted using the given subsectionExtractor. The given attributes will be made available during snippet generation.

Parameters:

partName - the name of the request part

subsectionExtractor - the subsection extractor

attributes - the attributes

Returns:

the snippet that will document the response body

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

beneathPath

public static PayloadSubsectionExtractor<?> beneathPath(String path)

Returns a PayloadSubsectionExtractor that will extract the subsection of the JSON payload found beneath the given path.

Parameters:

path - the path

Returns:

the subsection extractor

Since:

1.2.0