diff --git a/README.md b/README.md
index 6ee146f6..0e6dd919 100644
--- a/README.md
+++ b/README.md
@@ -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 ``.
+* 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
diff --git a/docs/index.html b/docs/index.html
index ec971967..9c446dd2 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -460,6 +460,12 @@
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 usage).
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 have to be created manally and must be tagged as [[overview-pagination]].
+See example project for paging section template.
diff --git a/spring-auto-restdocs-docs/constraints.adoc b/spring-auto-restdocs-docs/constraints.adoc
index 5e670e69..3731654e 100644
--- a/spring-auto-restdocs-docs/constraints.adoc
+++ b/spring-auto-restdocs-docs/constraints.adoc
@@ -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
diff --git a/spring-auto-restdocs-docs/getting-started.adoc b/spring-auto-restdocs-docs/getting-started.adoc
index 3d223b7a..a7433ceb 100644
--- a/spring-auto-restdocs-docs/getting-started.adoc
+++ b/spring-auto-restdocs-docs/getting-started.adoc
@@ -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;
@@ -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].
diff --git a/spring-auto-restdocs-docs/index.adoc b/spring-auto-restdocs-docs/index.adoc
index 8cb3403a..595efe9a 100644
--- a/spring-auto-restdocs-docs/index.adoc
+++ b/spring-auto-restdocs-docs/index.adoc
@@ -46,11 +46,11 @@ 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 <>).
include::getting-started.adoc[]
@@ -58,4 +58,6 @@ include::snippets.adoc[]
include::constraints.adoc[]
+include::other.adoc[]
+
include::contributing.adoc[]
diff --git a/spring-auto-restdocs-docs/other.adoc b/spring-auto-restdocs-docs/other.adoc
new file mode 100644
index 00000000..3a4571c6
--- /dev/null
+++ b/spring-auto-restdocs-docs/other.adoc
@@ -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 `` 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].
diff --git a/spring-auto-restdocs-docs/section-snippet.adoc b/spring-auto-restdocs-docs/section-snippet.adoc
index f56a8a5a..68a34551 100644
--- a/spring-auto-restdocs-docs/section-snippet.adoc
+++ b/spring-auto-restdocs-docs/section-snippet.adoc
@@ -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]]
diff --git a/spring-auto-restdocs-docs/snippets.adoc b/spring-auto-restdocs-docs/snippets.adoc
index e835a06e..3ddcd98d 100644
--- a/spring-auto-restdocs-docs/snippets.adoc
+++ b/spring-auto-restdocs-docs/snippets.adoc
@@ -25,7 +25,8 @@ GET /items
[[snippets-description]]
=== Description snippet
-link:{core-package}/misc/DescriptionSnippet.java[Description snippet] outputs the Controller's method's Javadoc. Currently only basic ` ` and `
` 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]
@@ -33,9 +34,11 @@ link:{core-package}/misc/DescriptionSnippet.java[Description snippet] outputs th
/**
* Returns list of all items.
*
- * Use query parameters to filter the list by:
- * - orderNumber
- * - type
+ * Use query parameters to filter the list by:
+ *
+ *
orderNumber
+ *
type
+ *
*/
@RequestMapping...
public ItemResponse getItems() { ... }
@@ -173,7 +176,8 @@ static class ItemUpdateRequest {
| description
| String
| true
-| Item description. +
+| Item description.
+
Size must be between 0 and 20 inclusive.
|===
@@ -217,7 +221,8 @@ static class ItemResponse {
| orderNumber
| Integer
| true
-| Item's order number. +
+| Item's order number.
+
Must be at least 1.
|===
diff --git a/spring-auto-restdocs-example/generated-docs/index.html b/spring-auto-restdocs-example/generated-docs/index.html
index 4424c6fb..58356e39 100644
--- a/spring-auto-restdocs-example/generated-docs/index.html
+++ b/spring-auto-restdocs-example/generated-docs/index.html
@@ -1064,7 +1064,7 @@