Add support for reusing a snippet to document common elements

This commit updates all of the Snippet implementations that take one or more descriptors to provide an and method that can be used to create a new Snippet that has additional descriptors. Closes gh-168

Author: wilkinsona

docs/src/docs/asciidoc/documenting-your-api.adoc

@@ -445,6 +445,45 @@ When documenting HTTP Headers, the test will fail if a documented header is not
 the request or response.
 
 
+
+[[documenting-your-api-reusing-snippets]]
+=== Reusing snippets
+
+It's common for an API that's being documented to have some features that are common
+across several of its resources. To avoid repetition when documenting such resources a
+`Snippet` configured with the common elements can be reused.
+
+First, create the `Snippet` that describes the common elements. For example:
+
+[source,java,indent=0]
+----
+include::{examples-dir}/com/example/SnippetReuse.java[tags=field]
+----
+
+Second, use this snippet and add further descriptors that are resource-specific. For
+example:
+
+[source,java,indent=0,role="primary"]
+.MockMvc
+----
+include::{examples-dir}/com/example/mockmvc/MockMvcSnippetReuse.java[tags=use]
+----
+<1> Reuse the `pagingLinks` `Snippet` calling `and` to add descriptors that are specific
+to the resource that is being documented.
+
+[source,java,indent=0,role="secondary"]
+.REST Assured
+----
+include::{examples-dir}/com/example/restassured/RestAssuredSnippetReuse.java[tags=use]
+----
+<1> Reuse the `pagingLinks` `Snippet` calling `and` to add descriptors that are specific
+to the resource that is being documented.
+
+The result of the example is that links with the rels `first`, `last`, `next`, `previous`,
+`alpha`, and `bravo` are all documented.
+
+
+
 [[documenting-your-api-constraints]]
 === Documenting constraints
 

docs/src/test/java/com/example/SnippetReuse.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2012-2016 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example;
+
+import org.springframework.restdocs.hypermedia.LinksSnippet;
+
+import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.linkWithRel;
+import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.links;
+
+public class SnippetReuse {
+
+// tag::field[]
+protected final LinksSnippet pagingLinks = links(
+linkWithRel("first").optional().description("The first page of results"),
+linkWithRel("last").optional().description("The last page of results"),
+linkWithRel("next").optional().description("The next page of results"),
+linkWithRel("prev").optional().description("The previous page of results"));
+// end::field[]
+
+}

docs/src/test/java/com/example/mockmvc/MockMvcSnippetReuse.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2012-2016 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.mockmvc;
+
+import com.example.SnippetReuse;
+
+import org.springframework.http.MediaType;
+import org.springframework.test.web.servlet.MockMvc;
+
+import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.linkWithRel;
+import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
+import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+public class MockMvcSnippetReuse extends SnippetReuse {
+
+private MockMvc mockMvc;
+
+public void documentation() throws Exception {
+// tag::use[]
+this.mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
+.andExpect(status().isOk())
+.andDo(document("example", this.pagingLinks.and( // <1>
+linkWithRel("alpha").description("Link to the alpha resource"),
+linkWithRel("bravo").description("Link to the bravo resource"))));
+// end::use[]
+}
+
+}

docs/src/test/java/com/example/restassured/RestAssuredSnippetReuse.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2012-2016 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.restassured;
+
+import com.example.SnippetReuse;
+import com.jayway.restassured.RestAssured;
+import com.jayway.restassured.specification.RequestSpecification;
+
+
+import static org.hamcrest.CoreMatchers.is;
+import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.linkWithRel;
+import static org.springframework.restdocs.restassured.RestAssuredRestDocumentation.document;
+
+public class RestAssuredSnippetReuse extends SnippetReuse {
+
+private RequestSpecification spec;
+
+public void documentation() throws Exception {
+// tag::use[]
+RestAssured.given(this.spec)
+.accept("application/json")
+.filter(document("example", this.pagingLinks.and( // <1>
+linkWithRel("alpha").description("Link to the alpha resource"),
+linkWithRel("bravo").description("Link to the bravo resource"))))
+.get("/").then().assertThat().statusCode(is(200));
+// end::use[]
+}
+
+}

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2015 the original author or authors.
+ * Copyright 2014-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -55,7 +55,7 @@ public static HeaderDescriptor headerWithName(String name) {
  * @return the snippet that will document the request headers
  * @see #headerWithName(String)
  */
-public static Snippet requestHeaders(HeaderDescriptor... descriptors) {
+public static RequestHeadersSnippet requestHeaders(HeaderDescriptor... descriptors) {
 return new RequestHeadersSnippet(Arrays.asList(descriptors));
 }
 
@@ -72,7 +72,7 @@ public static Snippet requestHeaders(HeaderDescriptor... descriptors) {
  * @return the snippet that will document the request headers
  * @see #headerWithName(String)
  */
-public static Snippet requestHeaders(Map<String, Object> attributes,
+public static RequestHeadersSnippet requestHeaders(Map<String, Object> attributes,
 HeaderDescriptor... descriptors) {
 return new RequestHeadersSnippet(Arrays.asList(descriptors), attributes);
 }
@@ -88,7 +88,8 @@ public static Snippet requestHeaders(Map<String, Object> attributes,
  * @return the snippet that will document the response headers
  * @see #headerWithName(String)
  */
-public static Snippet responseHeaders(HeaderDescriptor... descriptors) {
+public static ResponseHeadersSnippet responseHeaders(
+HeaderDescriptor... descriptors) {
 return new ResponseHeadersSnippet(Arrays.asList(descriptors));
 }
 
@@ -106,7 +107,7 @@ public static Snippet responseHeaders(HeaderDescriptor... descriptors) {
  * @return the snippet that will document the response headers
  * @see #headerWithName(String)
  */
-public static Snippet responseHeaders(Map<String, Object> attributes,
+public static ResponseHeadersSnippet responseHeaders(Map<String, Object> attributes,
 HeaderDescriptor... descriptors) {
 return new ResponseHeadersSnippet(Arrays.asList(descriptors), attributes);
 }

spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/RequestHeadersSnippet.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2015 the original author or authors.
+ * Copyright 2014-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,6 +16,8 @@
 
 package org.springframework.restdocs.headers;
 
+import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -27,6 +29,7 @@
  * A {@link Snippet} that documents the headers in a request.
  *
  * @author Andreas Evers
+ * @author Andy Wilkinson
  * @see HeaderDocumentation#requestHeaders(HeaderDescriptor...)
  * @see HeaderDocumentation#requestHeaders(Map, HeaderDescriptor...)
  */
@@ -60,4 +63,18 @@ protected Set<String> extractActualHeaders(Operation operation) {
 return operation.getRequest().getHeaders().keySet();
 }
 
+/**
+ * Returns a new {@code RequestHeadersSnippet} configured with this snippet's
+ * attributes and its descriptors combined with the given
+ * {@code additionalDescriptors}.
+ * @param additionalDescriptors the additional descriptors
+ * @return the new snippet
+ */
+public RequestHeadersSnippet and(HeaderDescriptor... additionalDescriptors) {
+List<HeaderDescriptor> combinedDescriptors = new ArrayList<>();
+combinedDescriptors.addAll(this.getHeaderDescriptors());
+combinedDescriptors.addAll(Arrays.asList(additionalDescriptors));
+return new RequestHeadersSnippet(combinedDescriptors, getAttributes());
+}
+
 }

spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/ResponseHeadersSnippet.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2015 the original author or authors.
+ * Copyright 2014-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,6 +16,8 @@
 
 package org.springframework.restdocs.headers;
 
+import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -27,6 +29,7 @@
  * A {@link Snippet} that documents the headers in a response.
  *
  * @author Andreas Evers
+ * @author Andy Wilkinson
  * @see HeaderDocumentation#responseHeaders(HeaderDescriptor...)
  * @see HeaderDocumentation#responseHeaders(Map, HeaderDescriptor...)
  */
@@ -60,4 +63,18 @@ protected Set<String> extractActualHeaders(Operation operation) {
 return operation.getResponse().getHeaders().keySet();
 }
 
+/**
+ * Returns a new {@code ResponseHeadersSnippet} configured with this snippet's
+ * attributes and its descriptors combined with the given
+ * {@code additionalDescriptors}.
+ * @param additionalDescriptors the additional descriptors
+ * @return the new snippet
+ */
+public final ResponseHeadersSnippet and(HeaderDescriptor... additionalDescriptors) {
+List<HeaderDescriptor> combinedDescriptors = new ArrayList<>();
+combinedDescriptors.addAll(this.getHeaderDescriptors());
+combinedDescriptors.addAll(Arrays.asList(additionalDescriptors));
+return new ResponseHeadersSnippet(combinedDescriptors, getAttributes());
+}
+
 }

spring-restdocs-core/src/main/java/org/springframework/restdocs/http/HttpDocumentation.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2015 the original author or authors.
+ * Copyright 2014-2016 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,8 +18,6 @@
 
 import java.util.Map;
 
-import org.springframework.restdocs.snippet.Snippet;
-
 /**
  * Static factory methods for documenting a RESTful API's HTTP requests.
  *
@@ -38,7 +36,7 @@ private HttpDocumentation() {
  *
  * @return the snippet that will document the HTTP request
  */
-public static Snippet httpRequest() {
+public static HttpRequestSnippet httpRequest() {
 return new HttpRequestSnippet();
 }
 
@@ -50,7 +48,7 @@ public static Snippet httpRequest() {
  * @param attributes the attributes
  * @return the snippet that will document the HTTP request
  */
-public static Snippet httpRequest(Map<String, Object> attributes) {
+public static HttpRequestSnippet httpRequest(Map<String, Object> attributes) {
 return new HttpRequestSnippet(attributes);
 }
 
@@ -60,7 +58,7 @@ public static Snippet httpRequest(Map<String, Object> attributes) {
  *
  * @return the snippet that will document the HTTP response
  */
-public static Snippet httpResponse() {
+public static HttpResponseSnippet httpResponse() {
 return new HttpResponseSnippet();
 }
 
@@ -72,7 +70,7 @@ public static Snippet httpResponse() {
  * @param attributes the attributes
  * @return the snippet that will document the HTTP response
  */
-public static Snippet httpResponse(Map<String, Object> attributes) {
+public static HttpResponseSnippet httpResponse(Map<String, Object> attributes) {
 return new HttpResponseSnippet(attributes);
 }