Spring/spring-restdocs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Allow descriptors to be provided as a List as well as via varags

Browse Source 
Closes gh-247
This commit is contained in:
Marcel Overdijk
2016-05-24 11:42:35 +02:00
committed by Andy Wilkinson
parent 7e116ae0cd
commit 5edc27fc99
4 changed files with 675 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/HeaderDocumentation.java
View File

@@ -17,6 +17,7 @@
package org.springframework.restdocs.headers;
import java.util.Arrays;
import java.util.List;
import java.util.Map;
import org.springframework.restdocs.snippet.Snippet;
@@ -59,6 +60,21 @@ public abstract class HeaderDocumentation {
return new RequestHeadersSnippet(Arrays.asList(descriptors));
}
/**
* Returns a new {@link Snippet} that will document the headers of the API operation's
* request. The headers will be documented using the given {@code descriptors}.
* <p>
* If a header is documented, is not marked as optional, and is not present in the
* request, a failure will occur.
*
* @param descriptors the descriptions of the request's headers
* @return the snippet that will document the request headers
* @see #headerWithName(String)
*/
public static RequestHeadersSnippet requestHeaders(List<HeaderDescriptor> descriptors) {
return new RequestHeadersSnippet(descriptors);
}
/**
* Returns a new {@link Snippet} that will document the headers of the API
* operations's request. The given {@code attributes} will be available during snippet
@@ -77,6 +93,24 @@ public abstract class HeaderDocumentation {
return new RequestHeadersSnippet(Arrays.asList(descriptors), attributes);
}
/**
* Returns a new {@link Snippet} that will document the headers of the API
* operations's request. The given {@code attributes} will be available during snippet
* generation and the headers will be documented using the given {@code descriptors}.
* <p>
* If a header is documented, is not marked as optional, and is not present in the
* request, a failure will occur.
*
* @param attributes the attributes
* @param descriptors the descriptions of the request's headers
* @return the snippet that will document the request headers
* @see #headerWithName(String)
*/
public static RequestHeadersSnippet requestHeaders(Map<String, Object> attributes,
List<HeaderDescriptor> descriptors) {
return new RequestHeadersSnippet(descriptors, attributes);
}
/**
* Returns a new {@link Snippet} that will document the headers of the API operation's
* response. The headers will be documented using the given {@code descriptors}.
@@ -93,6 +127,22 @@ public abstract class HeaderDocumentation {
return new ResponseHeadersSnippet(Arrays.asList(descriptors));
}
/**
* Returns a new {@link Snippet} that will document the headers of the API operation's
* response. The headers will be documented using the given {@code descriptors}.
* <p>
* If a header is documented, is not marked as optional, and is not present in the
* request, a failure will occur.
*
* @param descriptors the descriptions of the response's headers
* @return the snippet that will document the response headers
* @see #headerWithName(String)
*/
public static ResponseHeadersSnippet responseHeaders(
List<HeaderDescriptor> descriptors) {
return new ResponseHeadersSnippet(descriptors);
}
/**
* Returns a new {@link Snippet} that will document the headers of the API
* operations's response. The given {@code attributes} will be available during
@@ -112,4 +162,23 @@ public abstract class HeaderDocumentation {
return new ResponseHeadersSnippet(Arrays.asList(descriptors), attributes);
}
/**
* Returns a new {@link Snippet} that will document the headers of the API
* operations's response. The given {@code attributes} will be available during
* snippet generation and the headers will be documented using the given
* {@code descriptors}.
* <p>
* If a header is documented, is not marked as optional, and is not present in the
* response, a failure will occur.
*
* @param attributes the attributes
* @param descriptors the descriptions of the response's headers
* @return the snippet that will document the response headers
* @see #headerWithName(String)
*/
public static ResponseHeadersSnippet responseHeaders(Map<String, Object> attributes,
List<HeaderDescriptor> descriptors) {
return new ResponseHeadersSnippet(descriptors, attributes);
}
}

195
spring-restdocs-core/src/main/java/org/springframework/restdocs/hypermedia/HypermediaDocumentation.java
View File

@@ -17,6 +17,7 @@
package org.springframework.restdocs.hypermedia;
import java.util.Arrays;
import java.util.List;
import java.util.Map;
/**
@@ -66,6 +67,31 @@ public abstract class HypermediaDocumentation {
Arrays.asList(descriptors));
}
/**
* Returns a new {@code Snippet} that will document the links in the API operation's
* response. Links will be extracted from the response automatically based on its
* content type and will be documented using the given {@code descriptors}.
* <p>
* If a link is present in the response, but is not documented by one of the
* descriptors, a failure will occur when the snippet is invoked. Similarly, if a link
* is documented, is not marked as optional, and is not present in the response, a
* failure will also occur.
* <p>
* If you do not want to document a link, a link descriptor can be marked as
* {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
* generated snippet while avoiding the failure described above.
* <p>
* If a descriptor does not have a {@link LinkDescriptor#description(Object)
* description}, the {@link Link#getTitle() title} of the link will be used. If the
* link does not have a title a failure will occur.
*
* @param descriptors the descriptions of the response's links
* @return the snippet that will document the links
*/
public static LinksSnippet links(List<LinkDescriptor> descriptors) {
return new LinksSnippet(new ContentTypeLinkExtractor(), descriptors);
}
/**
* Returns a new {@code Snippet} that will document the links in the API operation's
* response. Links will be extracted from the response automatically based on its
@@ -86,6 +112,25 @@ public abstract class HypermediaDocumentation {
Arrays.asList(descriptors), true);
}
/**
* Returns a new {@code Snippet} that will document the links in the API operation's
* response. Links will be extracted from the response automatically based on its
* content type and will be documented using the given {@code descriptors}.
* <p>
* If a link is documented, is not marked as optional, and is not present in the
* response, a failure will occur. Any undocumented links will be ignored.
* <p>
* If a descriptor does not have a {@link LinkDescriptor#description(Object)
* description}, the {@link Link#getTitle() title} of the link will be used. If the
* link does not have a title a failure will occur.
*
* @param descriptors the descriptions of the response's links
* @return the snippet that will document the links
*/
public static LinksSnippet relaxedLinks(List<LinkDescriptor> descriptors) {
return new LinksSnippet(new ContentTypeLinkExtractor(), descriptors, true);
}
/**
* Returns a new {@code Snippet} that will document the links in the API call's
* response. The given {@code attributes} will be available during snippet generation.
@@ -115,6 +160,34 @@ public abstract class HypermediaDocumentation {
Arrays.asList(descriptors), attributes);
}
/**
* Returns a new {@code Snippet} that will document the links in the API call's
* response. The given {@code attributes} will be available during snippet generation.
* Links will be extracted from the response automatically based on its content type
* and will be documented using the given {@code descriptors}.
* <p>
* If a link is present in the response, but is not documented by one of the
* descriptors, a failure will occur when the snippet is invoked. Similarly, if a link
* is documented, is not marked as optional, and is not present in the response, a
* failure will also occur.
* <p>
* If you do not want to document a link, a link descriptor can be marked as
* {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
* generated snippet while avoiding the failure described above.
* <p>
* If a descriptor does not have a {@link LinkDescriptor#description(Object)
* description}, the {@link Link#getTitle() title} of the link will be used. If the
* link does not have a title a failure will occur.
*
* @param attributes the attributes
* @param descriptors the descriptions of the response's links
* @return the snippet that will document the links
*/
public static LinksSnippet links(Map<String, Object> attributes,
List<LinkDescriptor> descriptors) {
return new LinksSnippet(new ContentTypeLinkExtractor(), descriptors, attributes);
}
/**
* Returns a new {@code Snippet} that will document the links in the API call's
* response. The given {@code attributes} will be available during snippet generation.
@@ -138,6 +211,28 @@ public abstract class HypermediaDocumentation {
Arrays.asList(descriptors), attributes, true);
}
/**
* Returns a new {@code Snippet} that will document the links in the API call's
* response. The given {@code attributes} will be available during snippet generation.
* Links will be extracted from the response automatically based on its content type
* and will be documented using the given {@code descriptors}.
* <p>
* If a link is documented, is not marked as optional, and is not present in the
* response, a failure will occur. Any undocumented links will be ignored.
* <p>
* If a descriptor does not have a {@link LinkDescriptor#description(Object)
* description}, the {@link Link#getTitle() title} of the link will be used. If the
* link does not have a title a failure will occur.
*
* @param attributes the attributes
* @param descriptors the descriptions of the response's links
* @return the snippet that will document the links
*/
public static LinksSnippet relaxedLinks(Map<String, Object> attributes,
List<LinkDescriptor> descriptors) {
return new LinksSnippet(new ContentTypeLinkExtractor(), descriptors, attributes, true);
}
/**
* Returns a new {@code Snippet} that will document the links in the API operation's
* response. Links will be extracted from the response using the given
@@ -165,6 +260,33 @@ public abstract class HypermediaDocumentation {
return new LinksSnippet(linkExtractor, Arrays.asList(descriptors));
}
/**
* Returns a new {@code Snippet} that will document the links in the API operation's
* response. Links will be extracted from the response using the given
* {@code linkExtractor} and will be documented using the given {@code descriptors}.
* <p>
* If a link is present in the response, but is not documented by one of the
* descriptors, a failure will occur when the snippet is invoked. Similarly, if a link
* is documented, is not marked as optional, and is not present in the response, a
* failure will also occur.
* <p>
* If you do not want to document a link, a link descriptor can be marked as
* {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
* generated snippet while avoiding the failure described above.
* <p>
* If a descriptor does not have a {@link LinkDescriptor#description(Object)
* description}, the {@link Link#getTitle() title} of the link will be used. If the
* link does not have a title a failure will occur.
*
* @param linkExtractor used to extract the links from the response
* @param descriptors the descriptions of the response's links
* @return the snippet that will document the links
*/
public static LinksSnippet links(LinkExtractor linkExtractor,
List<LinkDescriptor> descriptors) {
return new LinksSnippet(linkExtractor, descriptors);
}
/**
* Returns a new {@code Snippet} that will document the links in the API operation's
* response. Links will be extracted from the response using the given
@@ -186,6 +308,27 @@ public abstract class HypermediaDocumentation {
return new LinksSnippet(linkExtractor, Arrays.asList(descriptors), true);
}
/**
* Returns a new {@code Snippet} that will document the links in the API operation's
* response. Links will be extracted from the response using the given
* {@code linkExtractor} and will be documented using the given {@code descriptors}.
* <p>
* If a link is documented, is not marked as optional, and is not present in the
* response, a failure will occur. Any undocumented links will be ignored.
* <p>
* If a descriptor does not have a {@link LinkDescriptor#description(Object)
* description}, the {@link Link#getTitle() title} of the link will be used. If the
* link does not have a title a failure will occur.
*
* @param linkExtractor used to extract the links from the response
* @param descriptors the descriptions of the response's links
* @return the snippet that will document the links
*/
public static LinksSnippet relaxedLinks(LinkExtractor linkExtractor,
List<LinkDescriptor> descriptors) {
return new LinksSnippet(linkExtractor, descriptors, true);
}
/**
* Returns a new {@code Snippet} that will document the links in the API operation's
* response. The given {@code attributes} will be available during snippet generation.
@@ -215,6 +358,35 @@ public abstract class HypermediaDocumentation {
return new LinksSnippet(linkExtractor, Arrays.asList(descriptors), attributes);
}
/**
* Returns a new {@code Snippet} that will document the links in the API operation's
* response. The given {@code attributes} will be available during snippet generation.
* Links will be extracted from the response using the given {@code linkExtractor} and
* will be documented using the given {@code descriptors}.
* <p>
* If a link is present in the response, but is not documented by one of the
* descriptors, a failure will occur when the snippet is invoked. Similarly, if a link
* is documented, is not marked as optional, and is not present in the response, a
* failure will also occur.
* <p>
* If you do not want to document a link, a link descriptor can be marked as
* {@link LinkDescriptor#ignored}. This will prevent it from appearing in the
* generated snippet while avoiding the failure described above.
* <p>
* If a descriptor does not have a {@link LinkDescriptor#description(Object)
* description}, the {@link Link#getTitle() title} of the link will be used. If the
* link does not have a title a failure will occur.
*
* @param attributes the attributes
* @param linkExtractor used to extract the links from the response
* @param descriptors the descriptions of the response's links
* @return the snippet that will document the links
*/
public static LinksSnippet links(LinkExtractor linkExtractor,
Map<String, Object> attributes, List<LinkDescriptor> descriptors) {
return new LinksSnippet(linkExtractor, descriptors, attributes);
}
/**
* Returns a new {@code Snippet} that will document the links in the API operation's
* response. The given {@code attributes} will be available during snippet generation.
@@ -239,6 +411,29 @@ public abstract class HypermediaDocumentation {
true);
}
/**
* Returns a new {@code Snippet} that will document the links in the API operation's
* response. The given {@code attributes} will be available during snippet generation.
* Links will be extracted from the response using the given {@code linkExtractor} and
* will be documented using the given {@code descriptors}.
* <p>
* If a link is documented, is not marked as optional, and is not present in the
* response, a failure will occur. Any undocumented links will be ignored.
* <p>
* If a descriptor does not have a {@link LinkDescriptor#description(Object)
* description}, the {@link Link#getTitle() title} of the link will be used. If the
* link does not have a title a failure will occur.
*
* @param attributes the attributes
* @param linkExtractor used to extract the links from the response
* @param descriptors the descriptions of the response's links
* @return the snippet that will document the links
*/
public static LinksSnippet relaxedLinks(LinkExtractor linkExtractor,
Map<String, Object> attributes, List<LinkDescriptor> descriptors) {
return new LinksSnippet(linkExtractor, descriptors, attributes, true);
}
/**
* Returns a {@code LinkExtractor} capable of extracting links in Hypermedia
* Application Language (HAL) format where the links are found in a map named

167
spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/PayloadDocumentation.java
View File

@@ -121,6 +121,29 @@ public abstract class PayloadDocumentation {
return new RequestFieldsSnippet(Arrays.asList(descriptors));
}
/**
* Returns a {@code Snippet} that will document the fields of the API operations's
* request payload. The fields will be documented using the given {@code descriptors}.
* <p>
* 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.
* <p>
* If you do not want to document a field, a field descriptor can be marked as
* {@link FieldDescriptor#ignored}. This will prevent it from appearing in the
* generated snippet while avoiding the failure described above.
*
* @param descriptors the descriptions of the request payload's fields
* @return the snippet that will document the fields
* @see #fieldWithPath(String)
*/
public static RequestFieldsSnippet requestFields(List<FieldDescriptor> descriptors) {
return new RequestFieldsSnippet(descriptors);
}
/**
* Returns a {@code Snippet} that will document the fields of the API operations's
* request payload. The fields will be documented using the given {@code descriptors}.
@@ -137,6 +160,22 @@ public abstract class PayloadDocumentation {
return new RequestFieldsSnippet(Arrays.asList(descriptors), true);
}
/**
* Returns a {@code Snippet} that will document the fields of the API operations's
* request payload. The fields will be documented using the given {@code descriptors}.
* <p>
* 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.
*
* @param descriptors the descriptions of the request payload's fields
* @return the snippet that will document the fields
* @see #fieldWithPath(String)
*/
public static RequestFieldsSnippet relaxedRequestFields(
List<FieldDescriptor> descriptors) {
return new RequestFieldsSnippet(descriptors, true);
}
/**
* Returns a {@code Snippet} that will document the fields of the API operation's
* request payload. The fields will be documented using the given {@code descriptors}
@@ -163,6 +202,32 @@ public abstract class PayloadDocumentation {
return new RequestFieldsSnippet(Arrays.asList(descriptors), attributes);
}
/**
* Returns a {@code Snippet} that will document the fields of the API operation's
* request payload. The fields will be documented using the given {@code descriptors}
* and the given {@code attributes} will be available during snippet generation.
* <p>
* 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.
* <p>
* If you do not want to document a field, a field descriptor can be marked as
* {@link FieldDescriptor#ignored}. This will prevent it from appearing in the
* generated snippet while avoiding the failure described above.
*
* @param attributes the attributes
* @param descriptors the descriptions of the request payload's fields
* @return the snippet that will document the fields
* @see #fieldWithPath(String)
*/
public static RequestFieldsSnippet requestFields(Map<String, Object> attributes,
List<FieldDescriptor> descriptors) {
return new RequestFieldsSnippet(descriptors, attributes);
}
/**
* Returns a {@code Snippet} that will document the fields of the API operation's
* request payload. The fields will be documented using the given {@code descriptors}
@@ -181,6 +246,24 @@ public abstract class PayloadDocumentation {
return new RequestFieldsSnippet(Arrays.asList(descriptors), attributes, true);
}
/**
* Returns a {@code Snippet} that will document the fields of the API operation's
* request payload. The fields will be documented using the given {@code descriptors}
* and the given {@code attributes} will be available during snippet generation.
* <p>
* 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.
*
* @param attributes the attributes
* @param descriptors the descriptions of the request payload's fields
* @return the snippet that will document the fields
* @see #fieldWithPath(String)
*/
public static RequestFieldsSnippet relaxedRequestFields(
Map<String, Object> attributes, List<FieldDescriptor> descriptors) {
return new RequestFieldsSnippet(descriptors, attributes, true);
}
/**
* Returns a {@code Snippet} that will document the fields of the API operation's
* response payload. The fields will be documented using the given {@code descriptors}
@@ -205,6 +288,30 @@ public abstract class PayloadDocumentation {
return new ResponseFieldsSnippet(Arrays.asList(descriptors));
}
/**
* Returns a {@code Snippet} that will document the fields of the API operation's
* response payload. The fields will be documented using the given {@code descriptors}
* .
* <p>
* 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.
* <p>
* If you do not want to document a field, a field descriptor can be marked as
* {@link FieldDescriptor#ignored}. This will prevent it from appearing in the
* generated snippet while avoiding the failure described above.
*
* @param descriptors the descriptions of the response payload's fields
* @return the snippet that will document the fields
* @see #fieldWithPath(String)
*/
public static ResponseFieldsSnippet responseFields(List<FieldDescriptor> descriptors) {
return new ResponseFieldsSnippet(descriptors);
}
/**
* Returns a {@code Snippet} that will document the fields of the API operation's
* response payload. The fields will be documented using the given {@code descriptors}
@@ -222,6 +329,23 @@ public abstract class PayloadDocumentation {
return new ResponseFieldsSnippet(Arrays.asList(descriptors), true);
}
/**
* Returns a {@code Snippet} that will document the fields of the API operation's
* response payload. The fields will be documented using the given {@code descriptors}
* .
* <p>
* 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.
*
* @param descriptors the descriptions of the response payload's fields
* @return the snippet that will document the fields
* @see #fieldWithPath(String)
*/
public static ResponseFieldsSnippet relaxedResponseFields(
List<FieldDescriptor> descriptors) {
return new ResponseFieldsSnippet(descriptors, true);
}
/**
* Returns a {@code Snippet} that will document the fields of the API operation's
* response payload. The fields will be documented using the given {@code descriptors}
@@ -248,6 +372,32 @@ public abstract class PayloadDocumentation {
return new ResponseFieldsSnippet(Arrays.asList(descriptors), attributes);
}
/**
* Returns a {@code Snippet} that will document the fields of the API operation's
* response payload. The fields will be documented using the given {@code descriptors}
* and the given {@code attributes} will be available during snippet generation.
* <p>
* 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.
* <p>
* If you do not want to document a field, a field descriptor can be marked as
* {@link FieldDescriptor#ignored}. This will prevent it from appearing in the
* generated snippet while avoiding the failure described above.
*
* @param attributes the attributes
* @param descriptors the descriptions of the response payload's fields
* @return the snippet that will document the fields
* @see #fieldWithPath(String)
*/
public static ResponseFieldsSnippet responseFields(Map<String, Object> attributes,
List<FieldDescriptor> descriptors) {
return new ResponseFieldsSnippet(descriptors, attributes);
}
/**
* Returns a {@code Snippet} that will document the fields of the API operation's
* response payload. The fields will be documented using the given {@code descriptors}
@@ -266,6 +416,23 @@ public abstract class PayloadDocumentation {
return new ResponseFieldsSnippet(Arrays.asList(descriptors), attributes, true);
}
/** Returns a {@code Snippet} that will document the fields of the API operation's
* response payload. The fields will be documented using the given {@code descriptors}
* and the given {@code attributes} will be available during snippet generation.
* <p>
* 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.
*
* @param attributes the attributes
* @param descriptors the descriptions of the response payload's fields
* @return the snippet that will document the fields
* @see #fieldWithPath(String)
*/
public static ResponseFieldsSnippet relaxedResponseFields(
Map<String, Object> attributes, List<FieldDescriptor> descriptors) {
return new ResponseFieldsSnippet(descriptors, attributes, true);
}
/**
* Creates a copy of the given {@code descriptors} with the given {@code pathPrefix}
* applied to their paths.

244
spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestDocumentation.java
View File

@@ -17,6 +17,7 @@
package org.springframework.restdocs.request;
import java.util.Arrays;
import java.util.List;
import java.util.Map;
import org.springframework.restdocs.operation.OperationRequest;
@@ -76,6 +77,28 @@ public abstract class RequestDocumentation {
return new PathParametersSnippet(Arrays.asList(descriptors));
}
/**
* Returns a {@code Snippet} that will document the path parameters from the API
* operation's request. The parameters will be documented using the given
* {@code descriptors}.
* <p>
* If a parameter is present in the request path, but is not documented by one of the
* descriptors, a failure will occur when the snippet is invoked. Similarly, if a
* parameter is documented, is not marked as optional, and is not present in the
* request path, a failure will also occur.
* <p>
* If you do not want to document a path parameter, a parameter descriptor can be
* marked as {@link ParameterDescriptor#ignored}. This will prevent it from appearing
* in the generated snippet while avoiding the failure described above.
*
* @param descriptors the descriptions of the parameters in the request's path
* @return the snippet that will document the parameters
*/
public static PathParametersSnippet pathParameters(
List<ParameterDescriptor> descriptors) {
return new PathParametersSnippet(descriptors);
}
/**
* Returns a {@code Snippet} that will document the path parameters from the API
* operation's request. The parameters will be documented using the given
@@ -92,6 +115,22 @@ public abstract class RequestDocumentation {
return new PathParametersSnippet(Arrays.asList(descriptors), true);
}
/**
* Returns a {@code Snippet} that will document the path parameters from the API
* operation's request. The parameters will be documented using the given
* {@code descriptors}.
* <p>
* If a parameter is documented, is not marked as optional, and is not present in the
* response, a failure will occur. Any undocumented parameters will be ignored.
*
* @param descriptors the descriptions of the parameters in the request's path
* @return the snippet that will document the parameters
*/
public static PathParametersSnippet relaxedPathParameters(
List<ParameterDescriptor> descriptors) {
return new PathParametersSnippet(descriptors, true);
}
/**
* Returns a {@code Snippet} that will document the path parameters from the API
* operation's request. The given {@code attributes} will be available during snippet
@@ -116,6 +155,30 @@ public abstract class RequestDocumentation {
return new PathParametersSnippet(Arrays.asList(descriptors), attributes);
}
/**
* Returns a {@code Snippet} that will document the path parameters from the API
* operation's request. The given {@code attributes} will be available during snippet
* rendering and the parameters will be documented using the given {@code descriptors}
* .
* <p>
* If a parameter is present in the request path, but is not documented by one of the
* descriptors, a failure will occur when the snippet is invoked. Similarly, if a
* parameter is documented, is not marked as optional, and is not present in the
* request path, a failure will also occur.
* <p>
* If you do not want to document a path parameter, a parameter descriptor can be
* marked as {@link ParameterDescriptor#ignored}. This will prevent it from appearing
* in the generated snippet while avoiding the failure described above.
*
* @param attributes the attributes
* @param descriptors the descriptions of the parameters in the request's path
* @return the snippet that will document the parameters
*/
public static PathParametersSnippet pathParameters(Map<String, Object> attributes,
List<ParameterDescriptor> descriptors) {
return new PathParametersSnippet(descriptors, attributes);
}
/**
* Returns a {@code Snippet} that will document the path parameters from the API
* operation's request. The given {@code attributes} will be available during snippet
@@ -134,6 +197,24 @@ public abstract class RequestDocumentation {
return new PathParametersSnippet(Arrays.asList(descriptors), attributes, true);
}
/**
* Returns a {@code Snippet} that will document the path parameters from the API
* operation's request. The given {@code attributes} will be available during snippet
* rendering and the parameters will be documented using the given {@code descriptors}
* .
* <p>
* If a parameter is documented, is not marked as optional, and is not present in the
* response, a failure will occur. Any undocumented parameters will be ignored.
*
* @param attributes the attributes
* @param descriptors the descriptions of the parameters in the request's path
* @return the snippet that will document the parameters
*/
public static PathParametersSnippet relaxedPathParameters(
Map<String, Object> attributes, List<ParameterDescriptor> descriptors) {
return new PathParametersSnippet(descriptors, attributes, true);
}
/**
* Returns a {@code Snippet} that will document the parameters from the API
* operation's request. The parameters will be documented using the given
@@ -157,6 +238,29 @@ public abstract class RequestDocumentation {
return new RequestParametersSnippet(Arrays.asList(descriptors));
}
/**
* Returns a {@code Snippet} that will document the parameters from the API
* operation's request. The parameters will be documented using the given
* {@code descriptors}.
* <p>
* If a parameter is present in the request, but is not documented by one of the
* descriptors, a failure will occur when the snippet is invoked. Similarly, if a
* parameter is documented, is not marked as optional, and is not present in the
* request, a failure will also occur.
* <p>
* If you do not want to document a request parameter, a parameter descriptor can be
* marked as {@link ParameterDescriptor#ignored}. This will prevent it from appearing
* in the generated snippet while avoiding the failure described above.
*
* @param descriptors The descriptions of the request's parameters
* @return the snippet
* @see OperationRequest#getParameters()
*/
public static RequestParametersSnippet requestParameters(
List<ParameterDescriptor> descriptors) {
return new RequestParametersSnippet(descriptors);
}
/**
* Returns a {@code Snippet} that will document the parameters from the API
* operation's request. The parameters will be documented using the given
@@ -174,6 +278,23 @@ public abstract class RequestDocumentation {
return new RequestParametersSnippet(Arrays.asList(descriptors), true);
}
/**
* Returns a {@code Snippet} that will document the parameters from the API
* operation's request. The parameters will be documented using the given
* {@code descriptors}.
* <p>
* If a parameter is documented, is not marked as optional, and is not present in the
* response, a failure will occur. Any undocumented parameters will be ignored.
*
* @param descriptors The descriptions of the request's parameters
* @return the snippet
* @see OperationRequest#getParameters()
*/
public static RequestParametersSnippet relaxedRequestParameters(
List<ParameterDescriptor> descriptors) {
return new RequestParametersSnippet(descriptors, true);
}
/**
* Returns a {@code Snippet} that will document the parameters from the API
* operation's request. The given {@code attributes} will be available during snippet
@@ -199,6 +320,31 @@ public abstract class RequestDocumentation {
return new RequestParametersSnippet(Arrays.asList(descriptors), attributes);
}
/**
* Returns a {@code Snippet} that will document the parameters from the API
* operation's request. The given {@code attributes} will be available during snippet
* rendering and the parameters will be documented using the given {@code descriptors}
* .
* <p>
* If a parameter is present in the request, but is not documented by one of the
* descriptors, a failure will occur when the snippet is invoked. Similarly, if a
* parameter is documented, is not marked as optional, and is not present in the
* request, a failure will also occur.
* <p>
* If you do not want to document a request parameter, a parameter descriptor can be
* marked as {@link ParameterDescriptor#ignored}. This will prevent it from appearing
* in the generated snippet while avoiding the failure described above.
*
* @param attributes the attributes
* @param descriptors the descriptions of the request's parameters
* @return the snippet that will document the parameters
* @see OperationRequest#getParameters()
*/
public static RequestParametersSnippet requestParameters(
Map<String, Object> attributes, List<ParameterDescriptor> descriptors) {
return new RequestParametersSnippet(descriptors, attributes);
}
/**
* Returns a {@code Snippet} that will document the parameters from the API
* operation's request. The given {@code attributes} will be available during snippet
@@ -218,6 +364,25 @@ public abstract class RequestDocumentation {
return new RequestParametersSnippet(Arrays.asList(descriptors), attributes, true);
}
/**
* Returns a {@code Snippet} that will document the parameters from the API
* operation's request. The given {@code attributes} will be available during snippet
* rendering and the parameters will be documented using the given {@code descriptors}
* .
* <p>
* If a parameter is documented, is not marked as optional, and is not present in the
* response, a failure will occur. Any undocumented parameters will be ignored.
*
* @param attributes the attributes
* @param descriptors the descriptions of the request's parameters
* @return the snippet that will document the parameters
* @see OperationRequest#getParameters()
*/
public static RequestParametersSnippet relaxedRequestParameters(
Map<String, Object> attributes, List<ParameterDescriptor> descriptors) {
return new RequestParametersSnippet(descriptors, attributes, true);
}
/**
* Returns a {@code Snippet} that will document the parts from the API operation's
* request. The parts will be documented using the given {@code descriptors}.
@@ -239,6 +404,27 @@ public abstract class RequestDocumentation {
return new RequestPartsSnippet(Arrays.asList(descriptors));
}
/**
* Returns a {@code Snippet} that will document the parts from the API operation's
* request. The parts will be documented using the given {@code descriptors}.
* <p>
* If a part is present in the request, but is not documented by one of the
* descriptors, a failure will occur when the snippet is invoked. Similarly, if a part
* is documented, is not marked as optional, and is not present in the request, a
* failure will also occur.
* <p>
* If you do not want to document a part, a part descriptor can be marked as
* {@link RequestPartDescriptor#ignored}. This will prevent it from appearing in the
* generated snippet while avoiding the failure described above.
*
* @param descriptors The descriptions of the request's parts
* @return the snippet
* @see OperationRequest#getParts()
*/
public static RequestPartsSnippet requestParts(List<RequestPartDescriptor> descriptors) {
return new RequestPartsSnippet(descriptors);
}
/**
* Returns a {@code Snippet} that will document the parts from the API operation's
* request. The parameters will be documented using the given {@code descriptors}.
@@ -255,6 +441,22 @@ public abstract class RequestDocumentation {
return new RequestPartsSnippet(Arrays.asList(descriptors), true);
}
/**
* Returns a {@code Snippet} that will document the parts from the API operation's
* request. The parameters will be documented using the given {@code descriptors}.
* <p>
* If a part is documented, is not marked as optional, and is not present in the
* request, a failure will occur. Any undocumented parts will be ignored.
*
* @param descriptors The descriptions of the request's parts
* @return the snippet
* @see OperationRequest#getParts()
*/
public static RequestPartsSnippet relaxedRequestParts(
List<RequestPartDescriptor> descriptors) {
return new RequestPartsSnippet(descriptors, true);
}
/**
* Returns a {@code Snippet} that will document the parts from the API operation's
* request. The given {@code attributes} will be available during snippet rendering
@@ -279,6 +481,30 @@ public abstract class RequestDocumentation {
return new RequestPartsSnippet(Arrays.asList(descriptors), attributes);
}
/**
* Returns a {@code Snippet} that will document the parts from the API operation's
* request. The given {@code attributes} will be available during snippet rendering
* and the parts will be documented using the given {@code descriptors}.
* <p>
* If a part is present in the request, but is not documented by one of the
* descriptors, a failure will occur when the snippet is invoked. Similarly, if a part
* is documented, is not marked as optional, and is not present in the request, a
* failure will also occur.
* <p>
* If you do not want to document a part, a part descriptor can be marked as
* {@link RequestPartDescriptor#ignored}. This will prevent it from appearing in the
* generated snippet while avoiding the failure described above.
*
* @param attributes the attributes
* @param descriptors the descriptions of the request's parts
* @return the snippet
* @see OperationRequest#getParts()
*/
public static RequestPartsSnippet requestParts(Map<String, Object> attributes,
List<RequestPartDescriptor> descriptors) {
return new RequestPartsSnippet(descriptors, attributes);
}
/**
* Returns a {@code Snippet} that will document the parts from the API operation's
* request. The given {@code attributes} will be available during snippet rendering
@@ -297,4 +523,22 @@ public abstract class RequestDocumentation {
return new RequestPartsSnippet(Arrays.asList(descriptors), attributes, true);
}
/**
* Returns a {@code Snippet} that will document the parts from the API operation's
* request. The given {@code attributes} will be available during snippet rendering
* and the parts will be documented using the given {@code descriptors}.
* <p>
* If a part is documented, is not marked as optional, and is not present in the
* request, a failure will occur. Any undocumented parts will be ignored.
*
* @param attributes the attributes
* @param descriptors the descriptions of the request's parts
* @return the snippet
* @see OperationRequest#getParameters()
*/
public static RequestPartsSnippet relaxedRequestParts(Map<String, Object> attributes,
List<RequestPartDescriptor> descriptors) {
return new RequestPartsSnippet(descriptors, attributes, true);
}
}