public abstract class PayloadDocumentation extends Object
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. |
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 RequestFieldsSnippet requestFields(FieldDescriptor... descriptors)
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.
descriptors
- the descriptions of the request payload's fieldsfieldWithPath(String)
public static RequestFieldsSnippet requestFields(List<FieldDescriptor> descriptors)
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.
descriptors
- the descriptions of the request payload's fieldsfieldWithPath(String)
public static RequestFieldsSnippet relaxedRequestFields(FieldDescriptor... descriptors)
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.
descriptors
- the descriptions of the request payload's fieldsfieldWithPath(String)
public static RequestFieldsSnippet relaxedRequestFields(List<FieldDescriptor> descriptors)
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.
descriptors
- the descriptions of the request payload's fieldsfieldWithPath(String)
public static RequestFieldsSnippet requestFields(Map<String,Object> attributes, FieldDescriptor... descriptors)
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.
attributes
- the attributesdescriptors
- the descriptions of the request payload's fieldsfieldWithPath(String)
public static RequestFieldsSnippet requestFields(Map<String,Object> attributes, List<FieldDescriptor> descriptors)
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.
attributes
- the attributesdescriptors
- the descriptions of the request payload's fieldsfieldWithPath(String)
public static RequestFieldsSnippet relaxedRequestFields(Map<String,Object> attributes, FieldDescriptor... descriptors)
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.
attributes
- the attributesdescriptors
- the descriptions of the request payload's fieldsfieldWithPath(String)
public static RequestFieldsSnippet relaxedRequestFields(Map<String,Object> attributes, List<FieldDescriptor> descriptors)
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.
attributes
- the attributesdescriptors
- the descriptions of the request payload's fieldsfieldWithPath(String)
public static ResponseFieldsSnippet responseFields(FieldDescriptor... descriptors)
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.
descriptors
- the descriptions of the response payload's fieldsfieldWithPath(String)
public static ResponseFieldsSnippet responseFields(List<FieldDescriptor> descriptors)
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.
descriptors
- the descriptions of the response payload's fieldsfieldWithPath(String)
public static ResponseFieldsSnippet relaxedResponseFields(FieldDescriptor... descriptors)
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.
descriptors
- the descriptions of the response payload's fieldsfieldWithPath(String)
public static ResponseFieldsSnippet relaxedResponseFields(List<FieldDescriptor> descriptors)
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.
descriptors
- the descriptions of the response payload's fieldsfieldWithPath(String)
public static ResponseFieldsSnippet responseFields(Map<String,Object> attributes, FieldDescriptor... descriptors)
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.
attributes
- the attributesdescriptors
- the descriptions of the response payload's fieldsfieldWithPath(String)
public static ResponseFieldsSnippet responseFields(Map<String,Object> attributes, List<FieldDescriptor> descriptors)
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.
attributes
- the attributesdescriptors
- the descriptions of the response payload's fieldsfieldWithPath(String)
public static ResponseFieldsSnippet relaxedResponseFields(Map<String,Object> attributes, FieldDescriptor... descriptors)
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.
attributes
- the attributesdescriptors
- the descriptions of the response payload's fieldsfieldWithPath(String)
public static ResponseFieldsSnippet relaxedResponseFields(Map<String,Object> attributes, List<FieldDescriptor> descriptors)
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.
attributes
- the attributesdescriptors
- the descriptions of the response payload's fieldsfieldWithPath(String)
public static List<FieldDescriptor> applyPathPrefix(String pathPrefix, List<FieldDescriptor> descriptors)
descriptors
with the given pathPrefix
applied to their paths.pathPrefix
- the path prefixdescriptors
- the descriptors to copy