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

Merge pull request #247 from Marcel Overdijk

Browse Source 
* gh-247:
  Polish "Allow descriptors to be provided as a List as well as via varags"
  Allow descriptors to be provided as a List as well as via varags
This commit is contained in:
Andy Wilkinson
2016-05-24 13:59:19 +01:00
parent 7e116ae0cd 81b2f11ebf
commit a0f82f283b
4 changed files with 797 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
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;
@@ -26,6 +27,7 @@ import org.springframework.restdocs.snippet.Snippet;
*
* @author Andreas Evers
* @author Andy Wilkinson
* @author Marcel Overdijk
*/
public abstract class HeaderDocumentation {
@@ -56,7 +58,23 @@ public abstract class HeaderDocumentation {
* @see #headerWithName(String)
*/
public static RequestHeadersSnippet requestHeaders(HeaderDescriptor... descriptors) {
return new RequestHeadersSnippet(Arrays.asList(descriptors));
return requestHeaders(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);
}
/**
@@ -74,7 +92,25 @@ public abstract class HeaderDocumentation {
*/
public static RequestHeadersSnippet requestHeaders(Map<String, Object> attributes,
HeaderDescriptor... descriptors) {
return new RequestHeadersSnippet(Arrays.asList(descriptors), attributes);
return requestHeaders(attributes, Arrays.asList(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
* 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);
}
/**
@@ -90,7 +126,23 @@ public abstract class HeaderDocumentation {
*/
public static ResponseHeadersSnippet responseHeaders(
HeaderDescriptor... descriptors) {
return new ResponseHeadersSnippet(Arrays.asList(descriptors));
return responseHeaders(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);
}
/**
@@ -109,7 +161,26 @@ public abstract class HeaderDocumentation {
*/
public static ResponseHeadersSnippet responseHeaders(Map<String, Object> attributes,
HeaderDescriptor... descriptors) {
return new ResponseHeadersSnippet(Arrays.asList(descriptors), attributes);
return responseHeaders(attributes, Arrays.asList(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
* 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);
}
}

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

@@ -17,12 +17,14 @@
package org.springframework.restdocs.hypermedia;
import java.util.Arrays;
import java.util.List;
import java.util.Map;
/**
* Static factory methods for documenting a RESTful API that utilizes Hypermedia.
*
* @author Andy Wilkinson
* @author Marcel Overdijk
*/
public abstract class HypermediaDocumentation {
@@ -62,8 +64,32 @@ public abstract class HypermediaDocumentation {
* @return the snippet that will document the links
*/
public static LinksSnippet links(LinkDescriptor... descriptors) {
return new LinksSnippet(new ContentTypeLinkExtractor(),
Arrays.asList(descriptors));
return links(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);
}
/**
@@ -82,8 +108,26 @@ public abstract class HypermediaDocumentation {
* @return the snippet that will document the links
*/
public static LinksSnippet relaxedLinks(LinkDescriptor... descriptors) {
return new LinksSnippet(new ContentTypeLinkExtractor(),
Arrays.asList(descriptors), true);
return relaxedLinks(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 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);
}
/**
@@ -111,8 +155,35 @@ public abstract class HypermediaDocumentation {
*/
public static LinksSnippet links(Map<String, Object> attributes,
LinkDescriptor... descriptors) {
return new LinksSnippet(new ContentTypeLinkExtractor(),
Arrays.asList(descriptors), attributes);
return links(attributes, Arrays.asList(descriptors));
}
/**
* 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);
}
/**
@@ -134,92 +205,14 @@ public abstract class HypermediaDocumentation {
*/
public static LinksSnippet relaxedLinks(Map<String, Object> attributes,
LinkDescriptor... descriptors) {
return new LinksSnippet(new ContentTypeLinkExtractor(),
Arrays.asList(descriptors), attributes, true);
return relaxedLinks(attributes, 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,
LinkDescriptor... descriptors) {
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 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,
LinkDescriptor... descriptors) {
return new LinksSnippet(linkExtractor, Arrays.asList(descriptors), true);
}
/**
* Returns a new {@code Snippet} that will document the links in the API operation's
* 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 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, LinkDescriptor... descriptors) {
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}.
* 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.
@@ -229,16 +222,215 @@ public abstract class HypermediaDocumentation {
* 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, LinkDescriptor... descriptors) {
return new LinksSnippet(linkExtractor, Arrays.asList(descriptors), attributes,
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
* {@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,
LinkDescriptor... descriptors) {
return links(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
* {@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,
LinkDescriptor... descriptors) {
return relaxedLinks(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 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.
* 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, LinkDescriptor... descriptors) {
return links(linkExtractor, attributes, Arrays.asList(descriptors));
}
/**
* 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.
* 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, LinkDescriptor... descriptors) {
return relaxedLinks(linkExtractor, attributes, Arrays.asList(descriptors));
}
/**
* 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

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

@@ -26,6 +26,7 @@ import java.util.Map;
*
* @author Andreas Evers
* @author Andy Wilkinson
* @author Marcel Overdijk
*/
public abstract class PayloadDocumentation {
@@ -118,7 +119,30 @@ public abstract class PayloadDocumentation {
* @see #fieldWithPath(String)
*/
public static RequestFieldsSnippet requestFields(FieldDescriptor... descriptors) {
return new RequestFieldsSnippet(Arrays.asList(descriptors));
return requestFields(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);
}
/**
@@ -134,7 +158,23 @@ public abstract class PayloadDocumentation {
*/
public static RequestFieldsSnippet relaxedRequestFields(
FieldDescriptor... descriptors) {
return new RequestFieldsSnippet(Arrays.asList(descriptors), true);
return relaxedRequestFields(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 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);
}
/**
@@ -160,7 +200,33 @@ public abstract class PayloadDocumentation {
*/
public static RequestFieldsSnippet requestFields(Map<String, Object> attributes,
FieldDescriptor... descriptors) {
return new RequestFieldsSnippet(Arrays.asList(descriptors), attributes);
return requestFields(attributes, Arrays.asList(descriptors));
}
/**
* 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);
}
/**
@@ -178,7 +244,25 @@ public abstract class PayloadDocumentation {
*/
public static RequestFieldsSnippet relaxedRequestFields(
Map<String, Object> attributes, FieldDescriptor... descriptors) {
return new RequestFieldsSnippet(Arrays.asList(descriptors), attributes, true);
return relaxedRequestFields(attributes, Arrays.asList(descriptors));
}
/**
* 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);
}
/**
@@ -202,7 +286,32 @@ public abstract class PayloadDocumentation {
* @see #fieldWithPath(String)
*/
public static ResponseFieldsSnippet responseFields(FieldDescriptor... descriptors) {
return new ResponseFieldsSnippet(Arrays.asList(descriptors));
return responseFields(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);
}
/**
@@ -219,7 +328,24 @@ public abstract class PayloadDocumentation {
*/
public static ResponseFieldsSnippet relaxedResponseFields(
FieldDescriptor... descriptors) {
return new ResponseFieldsSnippet(Arrays.asList(descriptors), true);
return relaxedResponseFields(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 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);
}
/**
@@ -245,7 +371,33 @@ public abstract class PayloadDocumentation {
*/
public static ResponseFieldsSnippet responseFields(Map<String, Object> attributes,
FieldDescriptor... descriptors) {
return new ResponseFieldsSnippet(Arrays.asList(descriptors), attributes);
return responseFields(attributes, 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}
* 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);
}
/**
@@ -263,7 +415,25 @@ public abstract class PayloadDocumentation {
*/
public static ResponseFieldsSnippet relaxedResponseFields(
Map<String, Object> attributes, FieldDescriptor... descriptors) {
return new ResponseFieldsSnippet(Arrays.asList(descriptors), attributes, true);
return relaxedResponseFields(attributes, 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}
* 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);
}
/**
@@ -280,8 +450,8 @@ public abstract class PayloadDocumentation {
for (FieldDescriptor descriptor : descriptors) {
FieldDescriptor prefixedDescriptor = new FieldDescriptor(
pathPrefix + descriptor.getPath())
.description(descriptor.getDescription())
.type(descriptor.getType());
.description(descriptor.getDescription())
.type(descriptor.getType());
if (descriptor.isIgnored()) {
prefixedDescriptor.ignored();
}

270
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;
@@ -25,6 +26,7 @@ import org.springframework.restdocs.operation.OperationRequest;
* Static factory methods for documenting aspects of a request sent to a RESTful API.
*
* @author Andy Wilkinson
* @author Marcel Overdijk
*/
public abstract class RequestDocumentation {
@@ -73,7 +75,29 @@ public abstract class RequestDocumentation {
*/
public static PathParametersSnippet pathParameters(
ParameterDescriptor... descriptors) {
return new PathParametersSnippet(Arrays.asList(descriptors));
return pathParameters(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);
}
/**
@@ -89,7 +113,23 @@ public abstract class RequestDocumentation {
*/
public static PathParametersSnippet relaxedPathParameters(
ParameterDescriptor... descriptors) {
return new PathParametersSnippet(Arrays.asList(descriptors), true);
return relaxedPathParameters(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 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);
}
/**
@@ -113,7 +153,31 @@ public abstract class RequestDocumentation {
*/
public static PathParametersSnippet pathParameters(Map<String, Object> attributes,
ParameterDescriptor... descriptors) {
return new PathParametersSnippet(Arrays.asList(descriptors), attributes);
return pathParameters(attributes, Arrays.asList(descriptors));
}
/**
* 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);
}
/**
@@ -131,7 +195,25 @@ public abstract class RequestDocumentation {
*/
public static PathParametersSnippet relaxedPathParameters(
Map<String, Object> attributes, ParameterDescriptor... descriptors) {
return new PathParametersSnippet(Arrays.asList(descriptors), attributes, true);
return relaxedPathParameters(attributes, Arrays.asList(descriptors));
}
/**
* 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);
}
/**
@@ -154,7 +236,30 @@ public abstract class RequestDocumentation {
*/
public static RequestParametersSnippet requestParameters(
ParameterDescriptor... descriptors) {
return new RequestParametersSnippet(Arrays.asList(descriptors));
return requestParameters(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);
}
/**
@@ -171,7 +276,24 @@ public abstract class RequestDocumentation {
*/
public static RequestParametersSnippet relaxedRequestParameters(
ParameterDescriptor... descriptors) {
return new RequestParametersSnippet(Arrays.asList(descriptors), true);
return relaxedRequestParameters(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 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);
}
/**
@@ -196,7 +318,32 @@ public abstract class RequestDocumentation {
*/
public static RequestParametersSnippet requestParameters(
Map<String, Object> attributes, ParameterDescriptor... descriptors) {
return new RequestParametersSnippet(Arrays.asList(descriptors), attributes);
return requestParameters(attributes, Arrays.asList(descriptors));
}
/**
* 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);
}
/**
@@ -215,7 +362,26 @@ public abstract class RequestDocumentation {
*/
public static RequestParametersSnippet relaxedRequestParameters(
Map<String, Object> attributes, ParameterDescriptor... descriptors) {
return new RequestParametersSnippet(Arrays.asList(descriptors), attributes, true);
return relaxedRequestParameters(attributes, Arrays.asList(descriptors));
}
/**
* 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);
}
/**
@@ -236,7 +402,29 @@ public abstract class RequestDocumentation {
* @see OperationRequest#getParts()
*/
public static RequestPartsSnippet requestParts(RequestPartDescriptor... descriptors) {
return new RequestPartsSnippet(Arrays.asList(descriptors));
return requestParts(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);
}
/**
@@ -252,7 +440,23 @@ public abstract class RequestDocumentation {
*/
public static RequestPartsSnippet relaxedRequestParts(
RequestPartDescriptor... descriptors) {
return new RequestPartsSnippet(Arrays.asList(descriptors), true);
return relaxedRequestParts(Arrays.asList(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}.
* <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);
}
/**
@@ -276,7 +480,31 @@ public abstract class RequestDocumentation {
*/
public static RequestPartsSnippet requestParts(Map<String, Object> attributes,
RequestPartDescriptor... descriptors) {
return new RequestPartsSnippet(Arrays.asList(descriptors), attributes);
return requestParts(attributes, Arrays.asList(descriptors));
}
/**
* 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);
}
/**
@@ -294,7 +522,25 @@ public abstract class RequestDocumentation {
*/
public static RequestPartsSnippet relaxedRequestParts(Map<String, Object> attributes,
RequestPartDescriptor... descriptors) {
return new RequestPartsSnippet(Arrays.asList(descriptors), attributes, true);
return relaxedRequestParts(attributes, Arrays.asList(descriptors));
}
/**
* 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);
}
}