Demonstrate mixing of Spring Auto REST Docs and Spring REST Docs (#199)

* Demonstrate mixing of Spring Auto REST Docs and Spring REST Docs

* Fix new FAQ entry

Author: fbenz

docs/index.html

@@ -546,6 +546,12 @@ <h2 id="faq"><a class="link" href="#faq">FAQ</a></h2>
 For advanced customization, multiple source directories for the JSON files
 can be configured (see <a href="#gettingstarted-usage">usage</a>).</p>
 </li>
+<li>
+<p><em>Can Spring REST Docs and Spring Auto REST Docs features be combined?</em></p>
+<p>Yes, this even works in the same test.
+One can generate Spring REST Docs snippets and Spring Auto REST Docs snippets out of the same test.
+This is demonstrated in the example project.</p>
+</li>
 </ol>
 </div>
 </div>
@@ -1767,7 +1773,7 @@ <h4 id="contributing-building-build"><a class="link" href="#contributing-buildin
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2018-01-03 18:23:11 CET
+Last updated 2018-01-06 21:38:23 CET
 </div>
 </div>
 <link rel="stylesheet" href="highlight/styles/github.min.css">

spring-auto-restdocs-docs/index.adoc

@@ -51,6 +51,10 @@ Is a multi-module project setup supported?::
   so modularization of codebase is fully supported.
   For advanced customization, multiple source directories for the JSON files
   can be configured (see <<gettingstarted-usage,usage>>).
+Can Spring REST Docs and Spring Auto REST Docs features be combined?::
+  Yes, this even works in the same test.
+  One can generate Spring REST Docs snippets and Spring Auto REST Docs snippets out of the same test.
+  This is demonstrated in the example project.
 
 include::getting-started.adoc[]
 

spring-auto-restdocs-example/generated-docs/index.html

@@ -449,6 +449,7 @@ <h1>Example API Documentation</h1>
 <li><a href="#resources-item-resource-test-process-single-item">2.9. Process One Item</a></li>
 <li><a href="#resources-item-resource-test-validate-metadata">2.10. Validate Metadata</a></li>
 <li><a href="#resources-item-resource-test-clone-item">2.11. Clone Item (deprecated)</a></li>
+<li><a href="#resources-items-get-spring-rest-docs">2.12. Get an item (SARD/SRD mix)</a></li>
 </ul>
 </li>
 </ul>
@@ -1121,7 +1122,7 @@ <h4 id="_example_request"><a class="anchor" href="#_example_request"></a><a clas
 <div class="content">
 <pre class="highlightjs highlight"><code class="language-bash" data-lang="bash">$ curl 'http://localhost:8080/items' -i -X POST \
     -H 'Content-Type: application/json' \
-    -H 'Authorization: Bearer 5ce7867e-0458-4378-8b94-a7133a194e47' \
+    -H 'Authorization: Bearer 5594beae-01ec-412b-9169-b69c30696c18' \
     -d '{"description":"Hot News"}'</code></pre>
 </div>
 </div>
@@ -1358,7 +1359,7 @@ <h4 id="_example_request_2"><a class="anchor" href="#_example_request_2"></a><a
 <div class="content">
 <pre class="highlightjs highlight"><code class="language-bash" data-lang="bash">$ curl 'http://localhost:8080/items/1' -i -X PUT \
     -H 'Content-Type: application/json' \
-    -H 'Authorization: Bearer 5ce7867e-0458-4378-8b94-a7133a194e47' \
+    -H 'Authorization: Bearer 5594beae-01ec-412b-9169-b69c30696c18' \
     -d '{"description":"Hot News"}'</code></pre>
 </div>
 </div>
@@ -1464,7 +1465,7 @@ <h4 id="_example_request_3"><a class="anchor" href="#_example_request_3"></a><a
 <div class="listingblock">
 <div class="content">
 <pre class="highlightjs highlight"><code class="language-bash" data-lang="bash">$ curl 'http://localhost:8080/items/1' -i -X DELETE \
-    -H 'Authorization: Bearer 5ce7867e-0458-4378-8b94-a7133a194e47'</code></pre>
+    -H 'Authorization: Bearer 5594beae-01ec-412b-9169-b69c30696c18'</code></pre>
 </div>
 </div>
 </div>
@@ -1949,19 +1950,19 @@ <h4 id="_example_response_5"><a class="anchor" href="#_example_response_5"></a><
     "page" : 0,
     "size" : 20,
     "sort" : null,
-    "offset" : 0,
     "pageNumber" : 0,
-    "pageSize" : 20
+    "pageSize" : 20,
+    "offset" : 0
   },
   "total" : 1,
-  "last" : true,
   "totalPages" : 1,
+  "last" : true,
   "totalElements" : 1,
-  "size" : 20,
-  "number" : 0,
   "sort" : null,
   "first" : true,
-  "numberOfElements" : 1
+  "numberOfElements" : 1,
+  "size" : 20,
+  "number" : 0
 }</code></pre>
 </div>
 </div>
@@ -2420,12 +2421,123 @@ <h4 id="_example_response_9"><a class="anchor" href="#_example_response_9"></a><
 </div>
 </div>
 </div>
+<div class="sect2">
+<h3 id="resources-items-get-spring-rest-docs"><a class="anchor" href="#resources-items-get-spring-rest-docs"></a><a class="link" href="#resources-items-get-spring-rest-docs">2.12. Get an item (SARD/SRD mix)</a></h3>
+<div class="paragraph">
+<p>This part of the documentation demonstrates the combination of Spring Auto REST Docs with Spring REST Docs:
+The path parameter and response field are manually documented with Spring REST Docs.
+The authorization is still coming from Spring Auto REST Docs and
+the cURL and HTTP response are coming from Spring REST Docs in any case.</p>
+</div>
+<div class="paragraph">
+<p><code>GET /items/{id}</code></p>
+</div>
+<div class="sect3">
+<h4 id="_authorization_12"><a class="anchor" href="#_authorization_12"></a><a class="link" href="#_authorization_12">2.12.1. Authorization</a></h4>
+<div class="paragraph">
+<p>OAuth2: Resource is public.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_path_parameters_11"><a class="anchor" href="#_path_parameters_11"></a><a class="link" href="#_path_parameters_11">2.12.2. Path parameters</a></h4>
+<table class="tableblock frame-all grid-all spread">
+<caption class="title">Table 3. /items/{id}</caption>
+<colgroup>
+<col style="width: 50%;">
+<col style="width: 50%;">
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top">Parameter</th>
+<th class="tableblock halign-left valign-top">Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>id</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">ID of the item.</p></td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="sect3">
+<h4 id="_response_fields_12"><a class="anchor" href="#_response_fields_12"></a><a class="link" href="#_response_fields_12">2.12.3. Response fields</a></h4>
+<table class="tableblock frame-all grid-all spread">
+<colgroup>
+<col style="width: 33.3333%;">
+<col style="width: 33.3333%;">
+<col style="width: 33.3334%;">
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top">Path</th>
+<th class="tableblock halign-left valign-top">Type</th>
+<th class="tableblock halign-left valign-top">Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>id</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>String</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">There are more fields but only the ID field is documented.</p></td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="sect3">
+<h4 id="_example_request_response_3"><a class="anchor" href="#_example_request_response_3"></a><a class="link" href="#_example_request_response_3">2.12.4. Example request/response</a></h4>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-bash" data-lang="bash">$ curl 'http://localhost:8080/items/1' -i</code></pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight nowrap"><code class="language-http" data-lang="http">HTTP/1.1 200 OK
+X-Content-Type-Options: nosniff
+X-XSS-Protection: 1; mode=block
+Cache-Control: no-cache, no-store, max-age=0, must-revalidate
+Pragma: no-cache
+Expires: 0
+X-Frame-Options: DENY
+Content-Type: application/json;charset=UTF-8
+Content-Length: 459
+
+{
+  "id" : "1",
+  "meta" : {
+    "type" : "1",
+    "tag" : "meta1"
+  },
+  "attributes" : {
+    "text" : "first item",
+    "number" : 1,
+    "bool" : true,
+    "decimal" : 1.11,
+    "amount" : "3.14 EUR",
+    "enumType" : "ONE"
+  },
+  "children" : [ {
+    "id" : "child-1",
+    "meta" : null,
+    "attributes" : null,
+    "children" : null,
+    "tags" : null,
+    "description" : "first child"
+  } ],
+  "tags" : [ "top-level" ],
+  "description" : "main item"
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
 </div>
 </div>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2017-11-02 11:03:07 CET
+Last updated 2018-01-06 21:26:54 CET
 </div>
 </div>
 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.9.1/styles/github.min.css">

spring-auto-restdocs-example/src/main/asciidoc/index.adoc

@@ -121,3 +121,4 @@ Pagination response has following structure:
 = Resources
 
 include::items.adoc[]
+include::srd-items.adoc[]

spring-auto-restdocs-example/src/main/asciidoc/srd-items.adoc

@@ -0,0 +1,26 @@
+[[resources-items-get-spring-rest-docs]]
+=== Get an item (SARD/SRD mix)
+
+This part of the documentation demonstrates the combination of Spring Auto REST Docs with Spring REST Docs:
+The path parameter and response field are manually documented with Spring REST Docs.
+The authorization is still coming from Spring Auto REST Docs and
+the cURL and HTTP response are coming from Spring REST Docs in any case.
+
+`GET /items/{id}`
+
+==== Authorization
+
+include::{snippets}/item-resource-test/get-item-with-rest-docs/auto-authorization.adoc[]
+
+==== Path parameters
+
+include::{snippets}/item-resource-test/get-item-with-rest-docs/path-parameters.adoc[]
+
+==== Response fields
+
+include::{snippets}/item-resource-test/get-item-with-rest-docs/response-fields.adoc[]
+
+==== Example request/response
+
+include::{snippets}/item-resource-test/get-item-with-rest-docs/curl-request.adoc[]
+include::{snippets}/item-resource-test/get-item-with-rest-docs/http-response.adoc[]

spring-auto-restdocs-example/src/test/java/capital/scalable/restdocs/example/items/ItemResourceTest.java

@@ -26,6 +26,10 @@
 import static org.hamcrest.Matchers.is;
 import static org.hamcrest.Matchers.nullValue;
 import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
+import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
+import static org.springframework.restdocs.payload.PayloadDocumentation.relaxedResponseFields;
+import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
+import static org.springframework.restdocs.request.RequestDocumentation.pathParameters;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.delete;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
@@ -40,6 +44,7 @@
 import capital.scalable.restdocs.example.testsupport.MockMvcBase;
 import org.junit.Test;
 import org.springframework.http.MediaType;
+import org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders;
 
 public class ItemResourceTest extends MockMvcBase {
 
@@ -155,4 +160,28 @@ public void cloneItem() throws Exception {
                 .content("{ \"name\": \"xyz\" }"))
                 .andExpect(status().isOk());
     }
+
+    /**
+     * This test demonstrates that Spring REST Docs can be used in a Spring Auto REST Docs setup.
+     * <p>
+     * All Spring Auto REST Docs snippets are created as well because of the setup in {@link MockMvcBase}.
+     * This is not a requirement and one could use a pure Spring REST Docs setup here.
+     * <p>
+     * The result of the manual documentation below ends up in path-parameters.adoc and response-fields.adoc and
+     * not in auto-path-parameters.adoc or auto-request-fields.adoc.
+     * So there is no conflict and one is free to decide which snippets are included in the documentation.
+     * <p>
+     * RestDocumentationRequestBuilders.get is required for Spring REST Docs' pathParameters to work.
+     * Spring AUTO Rest Docs works with both MockMvcRequestBuilders and RestDocumentationRequestBuilders.
+     */
+    @Test
+    public void getItemWithRestDocs() throws Exception {
+        mockMvc.perform(RestDocumentationRequestBuilders.get("/items/{id}", 1))
+                .andExpect(status().isOk())
+                .andDo(document("{class-name}/{method-name}", commonResponsePreprocessor(),
+                        pathParameters(
+                                parameterWithName("id").description("ID of the item.")),
+                        relaxedResponseFields(fieldWithPath("id")
+                                .description("There are more fields but only the ID field is documented."))));
+    }
 }