public abstract class PayloadDocumentation extends Object
| 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.
|
public static FieldDescriptor fieldWithPath(String path)
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" |
path - The path of the fieldFieldDescriptor ready for further configurationpublic static Snippet requestFields(FieldDescriptor... descriptors)
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.
descriptors - The descriptions of the request's fieldsfieldWithPath(String)public static Snippet requestFields(Map<String,Object> attributes, FieldDescriptor... descriptors)
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.
attributes - Attributes made available during rendering of the snippetdescriptors - The descriptions of the request's fieldsfieldWithPath(String)public static Snippet responseFields(FieldDescriptor... descriptors)
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.
descriptors - The descriptions of the response's fieldsfieldWithPath(String)public static Snippet responseFields(Map<String,Object> attributes, FieldDescriptor... descriptors)
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.
attributes - Attributes made available during rendering of the snippetdescriptors - The descriptions of the response's fieldsfieldWithPath(String)