Skip to content
This repository was archived by the owner on Dec 19, 2023. It is now read-only.

Commit 30b9ee1

Browse files
jmisurjmisur
authored
regenerated docs (#262)
1 parent ffa52cf commit 30b9ee1

File tree

8 files changed

+137
-88
lines changed

8 files changed

+137
-88
lines changed

‎docs/index.html‎

Lines changed: 73 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -443,7 +443,7 @@ <h1>Spring Auto REST Docs</h1>
443443
<li><a href="#gettingstarted-requirements">Requirements</a></li>
444444
<li><a href="#gettingstarted-usage">Usage</a></li>
445445
<li><a href="#gettingstarted-snapshot">Snapshot build</a></li>
446-
<li><a href="#gettingstarted-sample">Sample application</a></li>
446+
<li><a href="#gettingstarted-sample">Sample applications</a></li>
447447
</ul>
448448
</li>
449449
<li><a href="#snippets">Snippets</a>
@@ -463,7 +463,7 @@ <h1>Spring Auto REST Docs</h1>
463463
</li>
464464
<li><a href="#constraints">Documenting constraints</a>
465465
<ul class="sectlevel2">
466-
<li><a href="#constraints-optionality">Constraint that determine optionality</a></li>
466+
<li><a href="#constraints-optionality">Constraints that determine optionality</a></li>
467467
<li><a href="#constraints-custom">Custom constraints</a></li>
468468
<li><a href="#constraints-enums">Enums</a></li>
469469
<li><a href="#constraints-readable-values">Readable constraint values</a></li>
@@ -565,6 +565,17 @@ <h2 id="faq"><a class="link" href="#faq">FAQ</a></h2>
565565
One can generate Spring REST Docs snippets and Spring Auto REST Docs snippets out of the same test.
566566
This is demonstrated in the example project.</p>
567567
</li>
568+
<li>
569+
<p><em>Is Kotlin supported?</em></p>
570+
<p>Yes, Spring Auto REST Docs 1.0.13 and 2.0.0 introduced Kotlin support.
571+
Instead of the Javadoc Doclet one has to use the Dokka extension
572+
<code>spring-auto-restdocs-dokka-json</code>. The extension is only available as 2.0.x,
573+
but works with both version of Spring Auto REST Docs.</p>
574+
</li>
575+
<li>
576+
<p><em>Is Java 9 supported?</em></p>
577+
<p>Yes, see <a href="#getting-started">Getting Started</a>.</p>
578+
</li>
568579
</ol>
569580
</div>
570581
</div>
@@ -580,23 +591,30 @@ <h3 id="gettingstarted-requirements"><a class="link" href="#gettingstarted-requi
580591
<div class="ulist">
581592
<ul>
582593
<li>
583-
<p>Java 7</p>
594+
<p>Java 8 or Kotlin 1.2</p>
584595
</li>
585596
<li>
586-
<p>Spring REST Docs 2.0.2.RELEASE (see <a href="http://docs.spring.io/spring-restdocs/docs/2.0.2.RELEASE/reference/html5/">documentation</a>)</p>
597+
<p>Spring REST Docs 2.0.2.RELEASE (see <a href="http://docs.spring.io/spring-restdocs/docs/2.0.2.RELEASE/reference/html5/">documentation</a>)</p>
587598
</li>
588599
<li>
589600
<p>Jackson has to be used for creating and parsing JSON</p>
590601
</li>
591602
</ul>
592603
</div>
604+
<div class="paragraph">
605+
<p>For Java 7 and Spring REST Docs 1.2.x support,
606+
please use the 1.0.x version of Spring Auto REST Docs.</p>
607+
</div>
608+
<div class="paragraph">
609+
<p>For Java 9 support, use <code>spring-auto-restdocs-json-doclet-jdk9</code> as doclet dependency.</p>
610+
</div>
593611
</div>
594612
<div class="sect2">
595613
<h3 id="gettingstarted-usage"><a class="link" href="#gettingstarted-usage">Usage</a></h3>
596614
<div class="olist arabic">
597615
<ol class="arabic">
598616
<li>
599-
<p>Setup project for <a href="http://docs.spring.io/spring-restdocs/docs/2.0.2.RELEASE/reference/html5/#getting-started">Spring REST Docs</a></p>
617+
<p>Setup project for <a href="http://docs.spring.io/spring-restdocs/docs/2.0.2.RELEASE/reference/html5/#getting-started">Spring REST Docs</a></p>
600618
</li>
601619
<li>
602620
<p>Additional configuration for this extension:</p>
@@ -642,7 +660,7 @@ <h3 id="gettingstarted-usage"><a class="link" href="#gettingstarted-usage">Usage
642660
&lt;doclet&gt;capital.scalable.restdocs.jsondoclet.ExtractDocumentationAsJsonDoclet&lt;/doclet&gt;
643661
&lt;docletArtifact&gt;
644662
&lt;groupId&gt;capital.scalable&lt;/groupId&gt;
645-
&lt;artifactId&gt;spring-auto-restdocs-json-doclet&lt;/artifactId&gt;
663+
&lt;artifactId&gt;spring-auto-restdocs-json-doclet&lt;/artifactId&gt; <i class="conum" data-value="4"></i><b>(4)</b>
646664
&lt;version&gt;2.0.1&lt;/version&gt;
647665
&lt;/docletArtifact&gt;
648666
&lt;destDir&gt;generated-javadoc-json&lt;/destDir&gt; <i class="conum" data-value="3"></i><b>(3)</b>
@@ -674,6 +692,10 @@ <h3 id="gettingstarted-usage"><a class="link" href="#gettingstarted-usage">Usage
674692
Multiple directories can be listed by separating them with <code>,</code>.
675693
The directories are processed in order and only the first found JSON file is used.</td>
676694
</tr>
695+
<tr>
696+
<td><i class="conum" data-value="4"></i><b>4</b></td>
697+
<td>For Java 9 support, use <code>spring-auto-restdocs-json-doclet-jdk9</code> as doclet dependency.</td>
698+
</tr>
677699
</table>
678700
</div>
679701
<div class="listingblock">
@@ -689,7 +711,7 @@ <h3 id="gettingstarted-usage"><a class="link" href="#gettingstarted-usage">Usage
689711

690712
dependencies {
691713
testCompile group: 'capital.scalable', name: 'spring-auto-restdocs-core', version: '2.0.1' <i class="conum" data-value="1"></i><b>(1)</b>
692-
jsondoclet group: 'capital.scalable', name: 'spring-auto-restdocs-json-doclet', version: '2.0.1'
714+
jsondoclet group: 'capital.scalable', name: 'spring-auto-restdocs-json-doclet', version: '2.0.1' <i class="conum" data-value="4"></i><b>(4)</b>
693715
}
694716

695717
task jsonDoclet(type: Javadoc, dependsOn: compileJava) {
@@ -730,6 +752,10 @@ <h3 id="gettingstarted-usage"><a class="link" href="#gettingstarted-usage">Usage
730752
Multiple directories can be listed by separating them with <code>,</code>.
731753
The directories are processed in order and only the first found JSON file is used.</td>
732754
</tr>
755+
<tr>
756+
<td><i class="conum" data-value="4"></i><b>4</b></td>
757+
<td>For Java 9 support, use <code>spring-auto-restdocs-json-doclet-jdk9</code> as doclet dependency.</td>
758+
</tr>
733759
</table>
734760
</div>
735761
</li>
@@ -855,14 +881,23 @@ <h3 id="gettingstarted-snapshot"><a class="link" href="#gettingstarted-snapshot"
855881
</div>
856882
</div>
857883
<div class="sect2">
858-
<h3 id="gettingstarted-sample"><a class="link" href="#gettingstarted-sample">Sample application</a></h3>
884+
<h3 id="gettingstarted-sample"><a class="link" href="#gettingstarted-sample">Sample applications</a></h3>
859885
<div class="paragraph">
860-
<p><a href="https://github.com/ScaCap/spring-auto-restdocs/tree/master/spring-auto-restdocs-example">This project</a>
861-
includes a sample application that demonstrates most features.</p>
886+
<p>This projects includes a
887+
<a href="https://github.com/ScaCap/spring-auto-restdocs/tree/master/samples/java-webmvc">Java Web MVC example</a>,
888+
a
889+
<a href="https://github.com/ScaCap/spring-auto-restdocs/tree/master/samples/java-webtestclient">Java WebTestClient example</a>
890+
and a
891+
<a href="https://github.com/ScaCap/spring-auto-restdocs/tree/master/samples/kotlin-webmvc">Kotlin Web MVC example</a>
892+
application that demonstrate most features.</p>
862893
</div>
863894
<div class="paragraph">
864-
<p>The generated documentation of the example project can be viewed
865-
<a href="https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/master/spring-auto-restdocs-example/generated-docs/index.html">here</a>.</p>
895+
<p>The generated documentation can be viewed for the
896+
<a href="https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/master/samples/java-webmvc/generated-docs/index.html">Java Web MVC example</a>,
897+
the
898+
<a href="https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/master/samples/java-webtestclient/generated-docs/index.html">Java WebTestClient example</a>
899+
and the
900+
<a href="https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/master/samples/kotlin-webmvc/generated-docs/index.html">Kotlin Web MCV example</a>.</p>
866901
</div>
867902
</div>
868903
</div>
@@ -1522,11 +1557,10 @@ <h3 id="snippets-custom"><a class="link" href="#snippets-custom">Custom snippet<
15221557
<h3 id="snippets-customization"><a class="link" href="#snippets-customization">Snippet customization</a></h3>
15231558
<div class="paragraph">
15241559
<p>Provide your own template in <code>org/springframework/restdocs/templates/asciidoctor</code> (or <code>markdown</code>) package of your resources.
1525-
You can override <a href="https://github.com/spring-projects/spring-restdocs/tree/v2.0.2.RELEASE/spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates">REST Docs
1526-
templates</a>
1560+
You can override <a href="https://github.com/spring-projects/spring-restdocs/tree/v2.0.2.RELEASE/spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates">REST Docs templates</a>
15271561
and <a href="https://github.com/ScaCap/spring-auto-restdocs/tree/master/spring-auto-restdocs-core/src/main/resources/org/springframework/restdocs/templates">Auto REST Docs templates</a>.
15281562
Important is to omit <code>default-</code> part from the template name so that the resolution algorithm will prefer this custom template.
1529-
See also <a href="http://docs.spring.io/spring-restdocs/docs/2.0.2.RELEASE/reference/html5/#documenting-your-api-customizing-snippets">original documentation</a> for additional details.</p>
1563+
See also <a href="http://docs.spring.io/spring-restdocs/docs/2.0.2.RELEASE/reference/html5/#documenting-your-api-customizing-snippets">original documentation</a> for additional details.</p>
15301564
</div>
15311565
</div>
15321566
</div>
@@ -1579,21 +1613,37 @@ <h2 id="constraints"><a class="link" href="#constraints">Documenting constraints
15791613
</tbody>
15801614
</table>
15811615
<div class="sect2">
1582-
<h3 id="constraints-optionality"><a class="link" href="#constraints-optionality">Constraint that determine optionality</a></h3>
1616+
<h3 id="constraints-optionality"><a class="link" href="#constraints-optionality">Constraints that determine optionality</a></h3>
15831617
<div class="paragraph">
15841618
<p>The following three constraints are used to determine whether a field is optional.
15851619
Their descriptions are not included in the field descriptions.</p>
15861620
</div>
15871621
<div class="ulist">
15881622
<ul>
15891623
<li>
1590-
<p>NotNull (Bean Validation)</p>
1624+
<p>NotNull</p>
1625+
</li>
1626+
<li>
1627+
<p>NotEmpty</p>
1628+
</li>
1629+
<li>
1630+
<p>NotBlank</p>
1631+
</li>
1632+
</ul>
1633+
</div>
1634+
<div class="paragraph">
1635+
<p>Along with JSR-303 annotations, optionality is also determined based on:</p>
1636+
</div>
1637+
<div class="ulist">
1638+
<ul>
1639+
<li>
1640+
<p><code>required</code> parameter of <code>@RequestParam</code></p>
15911641
</li>
15921642
<li>
1593-
<p>NotEmpty (Hibernate Validator)</p>
1643+
<p>field type being <code>java.util.Optional</code></p>
15941644
</li>
15951645
<li>
1596-
<p>NotBlank (Hibernate Validator)</p>
1646+
<p>Koltin field being non-nullable</p>
15971647
</li>
15981648
</ul>
15991649
</div>
@@ -1606,7 +1656,7 @@ <h3 id="constraints-custom"><a class="link" href="#constraints-custom">Custom co
16061656
Each description is a property where the key is the full class name of the annotation suffixed with <code>.description</code>.
16071657
The value is the description and can contain placeholders for annotation methods,
16081658
e.g. <code>${value}</code> to get the content of <code>value()</code>.
1609-
For more details, see original documentation of <a href="http://docs.spring.io/spring-restdocs/docs/2.0.2.RELEASE/reference/html5/#documenting-your-api-constraints-describing">here</a>.</p>
1659+
For more details, see original documentation of <a href="http://docs.spring.io/spring-restdocs/docs/2.0.2.RELEASE/reference/html5/#documenting-your-api-constraints-describing">here</a>.</p>
16101660
</div>
16111661
<div class="paragraph">
16121662
<p>Example for the constraint annotation <code>myproject.constraints.OneOf</code>:</p>
@@ -1849,7 +1899,7 @@ <h4 id="contributing-building-testjar"><a class="link" href="#contributing-build
18491899
but if you ever want to upgrade the version of Spring REST Docs in this project this step has to be done.</p>
18501900
</div>
18511901
<div class="paragraph">
1852-
<p>We use version 2.0.2.RELEASE of Spring REST Docs in this example.</p>
1902+
<p>We use version 2.0.2.RELEASE of Spring REST Docs in this example.</p>
18531903
</div>
18541904
<div class="paragraph">
18551905
<p>You find the currently required version in <code>pom.xml</code>:</p>
@@ -1881,7 +1931,7 @@ <h4 id="contributing-building-testjar"><a class="link" href="#contributing-build
18811931
</div>
18821932
<div class="paragraph">
18831933
<p>Afterwards the test JAR is located at
1884-
<code>spring-restdocs/spring-restdocs-core/build/libs/spring-restdocs-core-2.0.2.RELEASE-test.jar</code>
1934+
<code>spring-restdocs/spring-restdocs-core/build/libs/spring-restdocs-core-2.0.2.RELEASE-test.jar</code>
18851935
and has to be installed with the Maven command shown in the section above.</p>
18861936
</div>
18871937
</div>
@@ -1901,7 +1951,7 @@ <h4 id="contributing-building-build"><a class="link" href="#contributing-buildin
19011951
<div id="footer">
19021952
<div id="footer-text">
19031953
Version 2.0.2-SNAPSHOT<br>
1904-
Last updated 2018-08-21 17:26:42 CEST
1954+
Last updated 2018-09-20 10:03:44 CEST
19051955
</div>
19061956
</div>
19071957
<link rel="stylesheet" href="highlight/styles/github.min.css">

‎samples/java-webmvc/generated-docs/index.html‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1145,7 +1145,7 @@ <h4 id="_example_request"><a class="anchor" href="#_example_request"></a><a clas
11451145
<div class="content">
11461146
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ curl 'http://localhost:8080/items' -i -X POST \
11471147
-H 'Content-Type: application/json' \
1148-
-H 'Authorization: Bearer f5f4f322-0af7-4c4b-b323-02f6fcf60514' \
1148+
-H 'Authorization: Bearer 412a28e4-f983-4b65-ace7-c287b1f34e33' \
11491149
-d '{"description":"Hot News"}'</code></pre>
11501150
</div>
11511151
</div>
@@ -1382,7 +1382,7 @@ <h4 id="_example_request_2"><a class="anchor" href="#_example_request_2"></a><a
13821382
<div class="content">
13831383
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ curl 'http://localhost:8080/items/1' -i -X PUT \
13841384
-H 'Content-Type: application/json' \
1385-
-H 'Authorization: Bearer f5f4f322-0af7-4c4b-b323-02f6fcf60514' \
1385+
-H 'Authorization: Bearer 412a28e4-f983-4b65-ace7-c287b1f34e33' \
13861386
-d '{"description":"Hot News"}'</code></pre>
13871387
</div>
13881388
</div>
@@ -1488,7 +1488,7 @@ <h4 id="_example_request_3"><a class="anchor" href="#_example_request_3"></a><a
14881488
<div class="listingblock">
14891489
<div class="content">
14901490
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ curl 'http://localhost:8080/items/1' -i -X DELETE \
1491-
-H 'Authorization: Bearer f5f4f322-0af7-4c4b-b323-02f6fcf60514'</code></pre>
1491+
-H 'Authorization: Bearer 412a28e4-f983-4b65-ace7-c287b1f34e33'</code></pre>
14921492
</div>
14931493
</div>
14941494
</div>
@@ -1980,22 +1980,22 @@ <h4 id="_example_response_5"><a class="anchor" href="#_example_response_5"></a><
19801980
"offset" : 0,
19811981
"pageSize" : 20,
19821982
"pageNumber" : 0,
1983-
"unpaged" : false,
1984-
"paged" : true
1983+
"paged" : true,
1984+
"unpaged" : false
19851985
},
19861986
"total" : 1,
1987-
"last" : true,
19881987
"totalPages" : 1,
19891988
"totalElements" : 1,
1989+
"last" : true,
19901990
"size" : 20,
19911991
"number" : 0,
19921992
"numberOfElements" : 1,
1993-
"first" : true,
19941993
"sort" : {
19951994
"orders" : [ ],
19961995
"sorted" : false,
19971996
"unsorted" : true
1998-
}
1997+
},
1998+
"first" : true
19991999
}</code></pre>
20002000
</div>
20012001
</div>
@@ -2237,7 +2237,7 @@ <h4 id="_response_fields_9"><a class="anchor" href="#_response_fields_9"></a><a
22372237
<h4 id="_example_request_7"><a class="anchor" href="#_example_request_7"></a><a class="link" href="#_example_request_7">2.9.6. Example request</a></h4>
22382238
<div class="listingblock">
22392239
<div class="content">
2240-
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ curl 'http://localhost:8080/items/1/process?command=increase' -i -X POST \
2240+
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ curl 'http://localhost:8080/items/1/process' -i -X POST \
22412241
-H 'Content-Type: application/x-www-form-urlencoded' \
22422242
-d 'command=increase'</code></pre>
22432243
</div>
@@ -2474,7 +2474,7 @@ <h4 id="_authorization_12"><a class="anchor" href="#_authorization_12"></a><a cl
24742474
<div class="sect3">
24752475
<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>
24762476
<table class="tableblock frame-all grid-all spread">
2477-
<caption class="title">Table 3. /items/{id}</caption>
2477+
<caption class="title">Table 3. <code>/items/{id}</code></caption>
24782478
<colgroup>
24792479
<col style="width: 50%;">
24802480
<col style="width: 50%;">

0 commit comments

Comments
 (0)