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

improved documentation and readme #137

Merged
merged 3 commits into from
Sep 1, 2017
Merged

improved documentation and readme #137

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3d2463c
improved documentation and readme
jmisur Aug 31, 2017
4b79d42
small fixes
jmisur Aug 31, 2017
4441068
pr feedback
jmisur Sep 1, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 19 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,27 +22,30 @@ from the Introducing Spring Auto REST Docs talk at Spring IO 2017 are also avail

## Documentation

* [Latest / master](https://scacap.github.io/spring-auto-restdocs)
[Current 1.0.8 release](https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/v1.0.8/docs/index.html) reference guide.

* [Version 1.0.8](https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/f0a49f1f3c429a7fd17c25e98806fc5bad08429c/docs/index.html)
Latest master [1.0.9-SNAPSHOT](https://scacap.github.io/spring-auto-restdocs) reference guide.

* [Version 1.0.7](https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/25464f899d96cba889e48de309f0ee878588afe2/docs/index.html)

* [Version 1.0.6](https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/b2a1bbb12f7a7ccf499bc81d6caebe8f7a449321/docs/index.html)

* [Version 1.0.5](https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/12ad534d101363edfd1d41b22507c602e004b489/docs/index.html)

* [Version 1.0.4](https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/3d78a2deb0f0a880c40426417f0cd0bfb02d34a6/docs/index.html)
Older releases:
[1.0.7](https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/v1.0.7/docs/index.html),
[1.0.6](https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/v1.0.6/docs/index.html),
[1.0.5](https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/v1.0.5/docs/index.html),
[1.0.4](https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/v1.0.4/docs/index.html).

## Main features

* Automatic documentation of request and response fields.
* Automatic documentation of path and query parameters.
* Automatic documentation of field and parameter constraints
* A helper to document authentication.
* A snippet that includes all other snippets.
* Shorten JSON arrays in example requests and responses.
* Replace binary example requests and responses with `<binary>`.
* Automatic documentation of
[request](https://scacap.github.io/spring-auto-restdocs/#snippets-request-fields) and
[response](https://scacap.github.io/spring-auto-restdocs/#snippets-response-fields) fields,
[path](https://scacap.github.io/spring-auto-restdocs/#snippets-path-parameters) and
[query](https://scacap.github.io/spring-auto-restdocs/#snippets-request-parameters) parameters using Jackson and Javadoc
* Automatic documentation of field and parameter
[optionality](https://scacap.github.io/spring-auto-restdocs/#constraints-optionality) and
[constraints](https://scacap.github.io/spring-auto-restdocs/#constraints) using JSR 303 annotations
* Automatic documentation of [entire endpoint](https://scacap.github.io/spring-auto-restdocs/#snippets-section) with [customizations](https://scacap.github.io/spring-auto-restdocs/#snippets-section-customization)
* A helper to document [authentication](https://scacap.github.io/spring-auto-restdocs/#snippets-authorization)
* Support for [paging](https://scacap.github.io/spring-auto-restdocs/#paging)
* Convenient [preprocessors](https://scacap.github.io/spring-auto-restdocs/#preprocessors)

## Usage

Expand Down
115 changes: 99 additions & 16 deletions docs/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -460,6 +460,12 @@ <h1>Spring Auto REST Docs</h1>
<li><a href="#constraints-groups">Constraint groups</a></li>
</ul>
</li>
<li><a href="#other">Other</a>
<ul class="sectlevel2">
<li><a href="#paging">Paging support</a></li>
<li><a href="#preprocessors">Preprocessors</a></li>
</ul>
</li>
<li><a href="#contributing">Contributing</a>
<ul class="sectlevel2">
<li><a href="#contributing-building">Building from source</a></li>
Expand Down Expand Up @@ -530,11 +536,11 @@ <h2 id="faq"><a class="link" href="#faq">FAQ</a></h2>
<li>
<p><em>Is a multi-module project setup supported?</em></p>
<p>The JSON doclet and the REST Docs snippets produce files.
Therefore, all results can be copied across modules or projects.
Instead of copying, multiple source directories for
the JSON files can be configured with the <code>javadocJsonDir</code> property.
Directories are separated by <code>,</code> and are processed in order
and only the first found JSON file is used.</p>
Therefore, all files should be placed on the filesystem.
JSON files will be additionally looked up from classpath,
so modularization of codebase is fully supported.
For advanced customization, multiple source directories for the JSON files
can be configured (see <a href="#gettingstarted-usage">usage</a>).</p>
</li>
</ol>
</div>
Expand Down Expand Up @@ -707,6 +713,7 @@ <h3 id="gettingstarted-usage"><a class="link" href="#gettingstarted-usage">Usage
<li>
<p>Configure MockMvc</p>
<div class="listingblock">
<div class="title">Test class</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java" data-lang="java">@Autowired
private WebApplicationContext context;
Expand Down Expand Up @@ -758,10 +765,12 @@ <h3 id="gettingstarted-usage"><a class="link" href="#gettingstarted-usage">Usage
<div class="sect2">
<h3 id="gettingstarted-sample"><a class="link" href="#gettingstarted-sample">Sample application</a></h3>
<div class="paragraph">
<p><a href="https://github.com/ScaCap/spring-auto-restdocs/tree/master/spring-auto-restdocs-example">This project</a> includes a sample application that demonstrates most features:</p>
<p><a href="https://github.com/ScaCap/spring-auto-restdocs/tree/master/spring-auto-restdocs-example">This project</a>
includes a sample application that demonstrates most features.</p>
</div>
<div class="paragraph">
<p>The generated documentation of the example project can be viewed <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>
<p>The generated documentation of the example project can be viewed
<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>
</div>
</div>
</div>
Expand Down Expand Up @@ -792,17 +801,20 @@ <h3 id="snippets-method-path"><a class="link" href="#snippets-method-path">Metho
<div class="sect2">
<h3 id="snippets-description"><a class="link" href="#snippets-description">Description snippet</a></h3>
<div class="paragraph">
<p><a href="https://github.com/ScaCap/spring-auto-restdocs/blob/master/spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/misc/DescriptionSnippet.java">Description snippet</a> outputs the Controller&#8217;s method&#8217;s Javadoc. Currently only basic <code>&lt;br&gt;</code> and <code>&lt;p&gt;</code> tags are supported.</p>
<p><a href="https://github.com/ScaCap/spring-auto-restdocs/blob/master/spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/misc/DescriptionSnippet.java">Description snippet</a> outputs the Controller&#8217;s method&#8217;s Javadoc.
Currently only basic <code>br</code>, <code>p</code>, <code>ul</code> and <code>li</code> tags are supported.</p>
</div>
<div class="listingblock">
<div class="title">Code</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java" data-lang="java">/**
* Returns list of all items.
* &lt;p&gt;
* Use query parameters to filter the list by:&lt;br&gt;
* - orderNumber&lt;br&gt;
* - type
* Use query parameters to filter the list by:
* &lt;ul&gt;
* &lt;li&gt;orderNumber&lt;/li&gt;
* &lt;li&gt;type&lt;/li&gt;
* &lt;/ul&gt;
*/
@RequestMapping...
public ItemResponse getItems() { ... }</code></pre>
Expand Down Expand Up @@ -989,8 +1001,8 @@ <h3 id="snippets-request-fields"><a class="link" href="#snippets-request-fields"
<td class="tableblock halign-left valign-top"><p class="tableblock">description</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Item description.<br>
Size must be between 0 and 20 inclusive.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Item description.
</p><p class="tableblock">Size must be between 0 and 20 inclusive.</p></td>
</tr>
</tbody>
</table>
Expand Down Expand Up @@ -1049,8 +1061,8 @@ <h3 id="snippets-response-fields"><a class="link" href="#snippets-response-field
<td class="tableblock halign-left valign-top"><p class="tableblock">orderNumber</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Integer</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">true</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Item&#8217;s order number.<br>
Must be at least 1.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Item&#8217;s order number.
</p><p class="tableblock">Must be at least 1.</p></td>
</tr>
</tbody>
</table>
Expand Down Expand Up @@ -1311,6 +1323,43 @@ <h2 id="constraints"><a class="link" href="#constraints">Documenting constraints
and the constraint groups to derive whether a field is optional
and to add the constraint descriptions to the field descriptions.</p>
</div>
<div class="listingblock">
<div class="title">Example</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java" data-lang="java">/**
* Username
*/
@NotNull
@Size(min = 2, max = 50)
private String username;</code></pre>
</div>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">Result</caption>
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
<col style="width: 25%;">
<col style="width: 25%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Parameter</th>
<th class="tableblock halign-left valign-top">Type</th>
<th class="tableblock halign-left valign-top">Optional</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">username</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">String</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Username.
</p><p class="tableblock">Size must be between 2 and 50.</p></td>
</tr>
</tbody>
</table>
<div class="sect2">
<h3 id="constraints-optionality"><a class="link" href="#constraints-optionality">Constraint that determine optionality</a></h3>
<div class="paragraph">
Expand Down Expand Up @@ -1476,6 +1525,40 @@ <h5 id="constraints-examples-fields"><a class="link" href="#constraints-examples
</div>
</div>
<div class="sect1">
<h2 id="other"><a class="link" href="#other">Other</a></h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="paging"><a class="link" href="#paging">Paging support</a></h3>
<div class="paragraph">
<p>Paging support in an endpoint is automatically recognized if request handler method contains <code>Pageable</code> parameter
and response is of type <code>Page</code>. This is then mentioned in request and response snippets by linking
to common section explaining the details of supported paging parameters/fields.
This section have to be created manally and must be tagged as <code>[[overview-pagination]]</code>.
See example project for <a href="https://github.com/ScaCap/spring-auto-restdocs/blob/master/spring-auto-restdocs-example/src/main/asciidoc/index.adoc#overview-pagination">paging section</a> template.</p>
</div>
</div>
<div class="sect2">
<h3 id="preprocessors"><a class="link" href="#preprocessors">Preprocessors</a></h3>
<div class="paragraph">
<p>Preprocessors are available for use in order to improve quality of endpoint examples.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="https://github.com/ScaCap/spring-auto-restdocs/blob/master//spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/response/BinaryReplacementContentModifier.java">binary replacement</a>: replaces content with <code>&lt;binary&gt;</code> for common mime types</p>
</li>
<li>
<p><a href="https://github.com/ScaCap/spring-auto-restdocs/blob/master//spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/response/ArrayLimitingJsonContentModifier.java">limit json array length</a>: limits all arrays in json to 3 items</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For list of standard preprocessors see <a href="https://github.com/spring-projects/spring-restdocs/blob/master/spring-restdocs-core/src/main/java/org/springframework/restdocs/operation/preprocess/Preprocessors.java">Preprocessors</a>.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="contributing"><a class="link" href="#contributing">Contributing</a></h2>
<div class="sectionbody">
<div class="sect2">
Expand Down Expand Up @@ -1554,7 +1637,7 @@ <h4 id="contributing-building-build"><a class="link" href="#contributing-buildin
</div>
<div id="footer">
<div id="footer-text">
Last updated 2017-08-30 22:08:32 CEST
Last updated 2017-09-01 00:15:29 CEST
</div>
</div>
<link rel="stylesheet" href="highlight/styles/github.min.css">
Expand Down
24 changes: 24 additions & 0 deletions spring-auto-restdocs-docs/constraints.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,30 @@ Here we are going a step further and automatically use constraints
and the constraint groups to derive whether a field is optional
and to add the constraint descriptions to the field descriptions.

.Example
[source,java]
----
/**
* Username
*/
@NotNull
@Size(min = 2, max = 50)
private String username;
----

.Result
|===
|Parameter|Type|Optional|Description

| username
| String
| false
| Username.

Size must be between 2 and 50.

|===

[[constraints-optionality]]
=== Constraint that determine optionality

Expand Down
7 changes: 5 additions & 2 deletions spring-auto-restdocs-docs/getting-started.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,7 @@ The directories are processed in order and only the first found JSON file is use
. Configure MockMvc
+
[source,java]
.Test class
----
@Autowired
private WebApplicationContext context;
Expand Down Expand Up @@ -174,6 +175,8 @@ public void setUp() throws Exception {
[[gettingstarted-sample]]
=== Sample application

https://github.com/ScaCap/spring-auto-restdocs/tree/master/spring-auto-restdocs-example[This project] includes a sample application that demonstrates most features:
https://github.com/ScaCap/spring-auto-restdocs/tree/master/spring-auto-restdocs-example[This project]
includes a sample application that demonstrates most features.

The generated documentation of the example project can be viewed https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/master/spring-auto-restdocs-example/generated-docs/index.html[here].
The generated documentation of the example project can be viewed
https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/master/spring-auto-restdocs-example/generated-docs/index.html[here].
12 changes: 7 additions & 5 deletions spring-auto-restdocs-docs/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,16 +46,18 @@ Is Jackson required for automatic field documentation?::
Yes, this project only includes a Jackson visitor so far.
Is a multi-module project setup supported?::
The JSON doclet and the REST Docs snippets produce files.
Therefore, all results can be copied across modules or projects.
Instead of copying, multiple source directories for
the JSON files can be configured with the `javadocJsonDir` property.
Directories are separated by `,` and are processed in order
and only the first found JSON file is used.
Therefore, all files should be placed on the filesystem.
JSON files will be additionally looked up from classpath,
so modularization of codebase is fully supported.
For advanced customization, multiple source directories for the JSON files
can be configured (see <<gettingstarted-usage,usage>>).

include::getting-started.adoc[]

include::snippets.adoc[]

include::constraints.adoc[]

include::other.adoc[]

include::contributing.adoc[]
26 changes: 26 additions & 0 deletions spring-auto-restdocs-docs/other.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
:master-dir: https://github.com/ScaCap/spring-auto-restdocs/blob/master
: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

[[other]]
== Other

[[paging]]
=== Paging support

Paging support in an endpoint is automatically recognized if request handler method contains `Pageable` parameter
and response is of type `Page`. This is then mentioned in request and response snippets by linking
to common section explaining the details of supported paging parameters/fields.
This section has to be created manally and must be tagged as `\[[overview-pagination]]`.
See example project for link:{example-dir}/src/main/asciidoc/index.adoc#overview-pagination[paging section] template.

[[preprocessors]]
=== Preprocessors

Preprocessors are available for use in order to improve quality of endpoint examples.

- link:{core-package}/response/BinaryReplacementContentModifier.java[binary replacement]: replaces content with `<binary>` for common mime types
- link:{core-package}/response/ArrayLimitingJsonContentModifier.java[limit JSON array length]: limits all JSON arrays to 3 items

For a list of standard preprocessors see link:{restdocs-package}/operation/preprocess/Preprocessors.java[Preprocessors].
2 changes: 0 additions & 2 deletions spring-auto-restdocs-docs/section-snippet.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
:core-dir: https://github.com/ScaCap/spring-auto-restdocs/blob/master/spring-auto-restdocs-core
:core-package: {core-dir}/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

[[snippets-section]]
Expand Down
17 changes: 11 additions & 6 deletions spring-auto-restdocs-docs/snippets.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,17 +25,20 @@ GET /items
[[snippets-description]]
=== Description snippet

link:{core-package}/misc/DescriptionSnippet.java[Description snippet] outputs the Controller's method's Javadoc. Currently only basic `<br>` and `<p>` tags are supported.
link:{core-package}/misc/DescriptionSnippet.java[Description snippet] outputs the Controller's method's Javadoc.
Currently only basic `br`, `p`, `ul` and `li` tags are supported.

.Code
[source,java]
----
/**
* Returns list of all items.
* <p>
* Use query parameters to filter the list by:<br>
* - orderNumber<br>
* - type
* Use query parameters to filter the list by:
* <ul>
* <li>orderNumber</li>
* <li>type</li>
* </ul>
*/
@RequestMapping...
public ItemResponse getItems() { ... }
Expand Down Expand Up @@ -173,7 +176,8 @@ static class ItemUpdateRequest {
| description
| String
| true
| Item description. +
| Item description.

Size must be between 0 and 20 inclusive.

|===
Expand Down Expand Up @@ -217,7 +221,8 @@ static class ItemResponse {
| orderNumber
| Integer
| true
| Item's order number. +
| Item's order number.

Must be at least 1.

|===
Expand Down
Loading