Snippet configuration documentation (#198)

* snippet configuration documentation

* review

* docs

Author: jmisur

docs/index.html

@@ -467,6 +467,7 @@ <h1>Spring Auto REST Docs</h1>
 <li><a href="#paging">Paging support</a></li>
 <li><a href="#preprocessors">Preprocessors</a></li>
 <li><a href="#deprecation">Deprecation support</a></li>
+<li><a href="#see-tag">See tag support</a></li>
 <li><a href="#localization">Localization support</a></li>
 </ul>
 </li>
@@ -949,6 +950,19 @@ <h3 id="snippets-path-parameters"><a class="link" href="#snippets-path-parameter
 </tr>
 </tbody>
 </table>
+<div class="sect3">
+<h4 id="_configuration"><a class="link" href="#_configuration">Configuration</a></h4>
+<div class="paragraph">
+<p>Configuration available during MockMvc setup:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>failOnUndocumentedParams</code> - if build should fail on at least one undocumented parameter</p>
+</li>
+</ul>
+</div>
+</div>
 </div>
 <div class="sect2">
 <h3 id="snippets-request-parameters"><a class="link" href="#snippets-request-parameters">Request parameters snippet</a></h3>
@@ -1001,6 +1015,19 @@ <h3 id="snippets-request-parameters"><a class="link" href="#snippets-request-par
 </tr>
 </tbody>
 </table>
+<div class="sect3">
+<h4 id="_configuration_2"><a class="link" href="#_configuration_2">Configuration</a></h4>
+<div class="paragraph">
+<p>Configuration available during MockMvc setup:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>failOnUndocumentedParams</code> - if build should fail on at least one undocumented parameter</p>
+</li>
+</ul>
+</div>
+</div>
 </div>
 <div class="sect2">
 <h3 id="snippets-request-headers"><a class="link" href="#snippets-request-headers">Request headers snippet</a></h3>
@@ -1105,6 +1132,22 @@ <h3 id="snippets-request-fields"><a class="link" href="#snippets-request-fields"
 </tr>
 </tbody>
 </table>
+<div class="sect3">
+<h4 id="_configuration_3"><a class="link" href="#_configuration_3">Configuration</a></h4>
+<div class="paragraph">
+<p>Configuration available during MockMvc setup:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>failOnUndocumentedFields</code> - if build should fail on at least one undocumented field</p>
+</li>
+<li>
+<p><code>requestBodyAsType</code> - specified class should be considered as request type instead of endpoint method&#8217;s parameter</p>
+</li>
+</ul>
+</div>
+</div>
 </div>
 <div class="sect2">
 <h3 id="snippets-response-fields"><a class="link" href="#snippets-response-fields">Response fields snippet</a></h3>
@@ -1165,6 +1208,22 @@ <h3 id="snippets-response-fields"><a class="link" href="#snippets-response-field
 </tr>
 </tbody>
 </table>
+<div class="sect3">
+<h4 id="_configuration_4"><a class="link" href="#_configuration_4">Configuration</a></h4>
+<div class="paragraph">
+<p>Configuration available during MockMvc setup:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>failOnUndocumentedFields</code> - if build should fail on at least one undocumented field</p>
+</li>
+<li>
+<p><code>responseBodyAsType</code> - specified class should be considered as response type instead of endpoint method&#8217;s return type</p>
+</li>
+</ul>
+</div>
+</div>
 </div>
 <div class="sect2">
 <h3 id="snippets-section"><a class="link" href="#snippets-section">Section snippet</a></h3>
@@ -1350,7 +1409,7 @@ <h5 id="snippets-section-customization-title"><a class="link" href="#snippets-se
 If missing, it&#8217;s derived from the method name, e.g. <code>getItemById</code> &#8594; <em>Get Item By Id</em>.</p>
 </div>
 <div class="paragraph">
-<p>If you use <code>@title</code> tag and want to generate regular Javadoc we well,
+<p>If you use <code>@title</code> tag and want to generate regular Javadoc as well,
 you need to include this tag among custom tags in plugin configuration.</p>
 </div>
 <div class="listingblock">
@@ -1671,12 +1730,20 @@ <h3 id="deprecation"><a class="link" href="#deprecation">Deprecation support</a>
 </ul>
 </div>
 <div class="paragraph">
-<p>The deprecation is only visible when using <a href="#snippets-section">Section</a> approach. Then it will be shown in the title (also visible in
-TOC) and description. Field&#8217;s deprecation is shown in description column of request/response table.
+<p>Deprecation is shown in the title of an endpoint (also visible in TOC) and description.
+Field&#8217;s deprecation is shown in description column of request/response table.<br>
 See how it looks in the <a href="https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/master/spring-auto-restdocs-example/generated-docs/index.html#resources-item-resource-test-clone-item">example project</a>.</p>
 </div>
 </div>
 <div class="sect2">
+<h3 id="see-tag"><a class="link" href="#see-tag">See tag support</a></h3>
+<div class="paragraph">
+<p><code>@see</code> Javadoc tag comment will be added to the main description section of an endpoint or a field.<br>
+Currently supports only HTML links. Does not support Java code references.<br>
+See how it looks in the <a href="https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/master/spring-auto-restdocs-example/generated-docs/index.html#resources-item-resource-test-search">example project</a>.</p>
+</div>
+</div>
+<div class="sect2">
 <h3 id="localization"><a class="link" href="#localization">Localization support</a></h3>
 <div class="paragraph">
 <p>For custom translations of section titles, table headers and other messages:</p>
@@ -1773,7 +1840,7 @@ <h4 id="contributing-building-build"><a class="link" href="#contributing-buildin
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2018-01-06 21:38:23 CET
+Last updated 2018-01-09 13:17:48 CET
 </div>
 </div>
 <link rel="stylesheet" href="highlight/styles/github.min.css">

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/AutoDocumentation.java

@@ -43,23 +43,23 @@ public static JacksonResponseFieldSnippet responseFields() {
         return new JacksonResponseFieldSnippet();
     }
 
-    public static Snippet pathParameters() {
+    public static PathParametersSnippet pathParameters() {
         return new PathParametersSnippet();
     }
 
-    public static Snippet requestHeaders() {
+    public static RequestHeaderSnippet requestHeaders() {
         return new RequestHeaderSnippet();
     }
 
-    public static Snippet requestParameters() {
+    public static RequestParametersSnippet requestParameters() {
         return new RequestParametersSnippet();
     }
 
-    public static Snippet description() {
+    public static DescriptionSnippet description() {
         return new DescriptionSnippet();
     }
 
-    public static Snippet methodAndPath() {
+    public static MethodAndPathSnippet methodAndPath() {
         return new MethodAndPathSnippet();
     }
 

spring-auto-restdocs-docs/other.adoc

@@ -2,6 +2,7 @@
 :example-dir: {master-dir}/spring-auto-restdocs-example
 :core-package: {master-dir}//spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs
 :restdocs-package: https://github.com/spring-projects/spring-restdocs/blob/master/spring-restdocs-core/src/main/java/org/springframework/restdocs
+:html-preview: https://htmlpreview.github.io/?
 
 [[other]]
 == Other
@@ -33,9 +34,16 @@ Endpoint or field will be marked as deprecated if at least one of these is prese
 - method / field is annotated with `@Deprecated`
 - method's / field's Javadoc has `@deprecated` tag
 
-The deprecation is only visible when using <<snippets-section,Section>> approach. Then it will be shown in the title (also visible in
-TOC) and description. Field's deprecation is shown in description column of request/response table.
-See how it looks in the link:https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/master/spring-auto-restdocs-example/generated-docs/index.html#resources-item-resource-test-clone-item[example project].
+Deprecation is shown in the title of an endpoint (also visible in TOC) and description.
+Field's deprecation is shown in description column of request/response table. +
+See how it looks in the link:{html-preview}{example-dir}/generated-docs/index.html#resources-item-resource-test-clone-item[example project].
+
+[[see-tag]]
+=== See tag support
+
+`@see` Javadoc tag comment will be added to the main description section of an endpoint or a field. +
+Currently supports only HTML links. Does not support Java code references. +
+See how it looks in the link:{html-preview}{example-dir}/generated-docs/index.html#resources-item-resource-test-search[example project].
 
 [[localization]]
 === Localization support

spring-auto-restdocs-docs/section-snippet.adoc

@@ -125,7 +125,7 @@ AutoDocumentation.sectionBuilder()
 Section title uses text from `@title` Javadoc tag on the handler method.
 If missing, it's derived from the method name, e.g. `getItemById` -> _Get Item By Id_.
 
-If you use `@title` tag and want to generate regular Javadoc we well,
+If you use `@title` tag and want to generate regular Javadoc as well,
 you need to include this tag among custom tags in plugin configuration.
 
 .Custom maven-javadoc-plugin configuration

spring-auto-restdocs-docs/snippets.adoc

@@ -111,6 +111,12 @@ public ItemResponse getItem(@PathVariable String id) { ... }
 
 |===
 
+==== Configuration
+
+Configuration available during MockMvc setup:
+
+- `failOnUndocumentedParams` - if build should fail on at least one undocumented parameter
+
 [[snippets-request-parameters]]
 === Request parameters snippet
 
@@ -148,6 +154,12 @@ Default value: "en".
 
 |===
 
+==== Configuration
+
+Configuration available during MockMvc setup:
+
+- `failOnUndocumentedParams` - if build should fail on at least one undocumented parameter
+
 [[snippets-request-headers]]
 === Request headers snippet
 
@@ -223,6 +235,13 @@ Size must be between 0 and 20 inclusive.
 
 |===
 
+==== Configuration
+
+Configuration available during MockMvc setup:
+
+- `failOnUndocumentedFields` - if build should fail on at least one undocumented field
+- `requestBodyAsType` - specified class should be considered as request type instead of endpoint method's parameter
+
 [[snippets-response-fields]]
 === Response fields snippet
 
@@ -268,6 +287,13 @@ Must be at least 1.
 
 |===
 
+==== Configuration
+
+Configuration available during MockMvc setup:
+
+- `failOnUndocumentedFields` - if build should fail on at least one undocumented field
+- `responseBodyAsType` - specified class should be considered as response type instead of endpoint method's return type
+
 include::section-snippet.adoc[]
 
 [[snippets-custom]]

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

@@ -1122,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 5594beae-01ec-412b-9169-b69c30696c18' \
+    -H 'Authorization: Bearer d6876398-3ace-4051-bf6f-4d21049d3f6d' \
     -d '{"description":"Hot News"}'</code></pre>
 </div>
 </div>
@@ -1359,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 5594beae-01ec-412b-9169-b69c30696c18' \
+    -H 'Authorization: Bearer d6876398-3ace-4051-bf6f-4d21049d3f6d' \
     -d '{"description":"Hot News"}'</code></pre>
 </div>
 </div>
@@ -1465,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 5594beae-01ec-412b-9169-b69c30696c18'</code></pre>
+    -H 'Authorization: Bearer d6876398-3ace-4051-bf6f-4d21049d3f6d'</code></pre>
 </div>
 </div>
 </div>
@@ -1950,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,
-    "offset" : 0
+    "pageSize" : 20
   },
   "total" : 1,
   "totalPages" : 1,
-  "last" : true,
   "totalElements" : 1,
+  "last" : true,
+  "size" : 20,
+  "number" : 0,
   "sort" : null,
-  "first" : true,
   "numberOfElements" : 1,
-  "size" : 20,
-  "number" : 0
+  "first" : true
 }</code></pre>
 </div>
 </div>
@@ -2537,7 +2537,7 @@ <h4 id="_example_request_response_3"><a class="anchor" href="#_example_request_r
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2018-01-06 21:26:54 CET
+Last updated 2018-01-09 13:15:28 CET
 </div>
 </div>
 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.9.1/styles/github.min.css">