Add support for using REST Assured to generate documentation snippets

This commit adds a new module, spring-restdocs-restassured, that
can be used to generate documentation snippets when testing a service
with REST Assured.

Please refer to the updated reference documentation for details.

Thanks to Johan Haleby for making a change to REST Assured so that
path parameters could be documented.

Closes gh-102

Author: wilkinsona

build.gradle

@@ -58,6 +58,7 @@ subprojects {
 		}
 		dependencies {
 			dependency 'com.fasterxml.jackson.core:jackson-databind:2.4.6.1'
+			dependency 'com.jayway.restassured:rest-assured:2.8.0'
 			dependency 'com.samskivert:jmustache:1.11'
 			dependency 'commons-codec:commons-codec:1.10'
 			dependency 'javax.servlet:javax.servlet-api:3.1.0'

config/checkstyle/checkstyle.xml

@@ -73,7 +73,7 @@
 		<module name="AvoidStarImport" />
 		<module name="AvoidStaticImport">
 			<property name="excludes"
-				value="org.junit.Assert.*, org.junit.Assume.*, org.hamcrest.CoreMatchers.*, org.hamcrest.Matchers.*, org.mockito.Mockito.*, org.mockito.BDDMockito.*, org.mockito.Matchers.*, org.springframework.restdocs.curl.CurlDocumentation.*, org.springframework.restdocs.headers.HeaderDocumentation.*, org.springframework.restdocs.hypermedia.HypermediaDocumentation.*, org.springframework.restdocs.mockmvc.IterableEnumeration.*, org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.*, org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.*, org.springframework.restdocs.payload.PayloadDocumentation.*, org.springframework.restdocs.operation.preprocess.Preprocessors.*, org.springframework.restdocs.request.RequestDocumentation.*, org.springframework.restdocs.snippet.Attributes.*, org.springframework.restdocs.test.SnippetMatchers.*, org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*, org.springframework.test.web.servlet.result.MockMvcResultMatchers.*" />
+				value="com.jayway.restassured.RestAssured.*, org.junit.Assert.*, org.junit.Assume.*, org.hamcrest.CoreMatchers.*, org.hamcrest.Matchers.*, org.mockito.Mockito.*, org.mockito.BDDMockito.*, org.mockito.Matchers.*, org.springframework.restdocs.curl.CurlDocumentation.*, org.springframework.restdocs.headers.HeaderDocumentation.*, org.springframework.restdocs.hypermedia.HypermediaDocumentation.*, org.springframework.restdocs.mockmvc.IterableEnumeration.*, org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.*, org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.*, org.springframework.restdocs.payload.PayloadDocumentation.*, org.springframework.restdocs.operation.preprocess.Preprocessors.*, org.springframework.restdocs.request.RequestDocumentation.*, org.springframework.restdocs.restassured.RestAssuredRestDocumentation.*, org.springframework.restdocs.restassured.operation.preprocess.RestAssuredPreprocessors.*, org.springframework.restdocs.snippet.Attributes.*, org.springframework.restdocs.test.SnippetMatchers.*, org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*, org.springframework.test.web.servlet.result.MockMvcResultMatchers.*" />
 		</module>
 		<module name="IllegalImport" />
 		<module name="RedundantImport" />

docs/build.gradle

@@ -4,6 +4,7 @@ plugins {
 
 dependencies {
 	testCompile project(':spring-restdocs-mockmvc')
+	testCompile project(':spring-restdocs-restassured')
 	testCompile 'javax.validation:validation-api'
 }
 

docs/src/docs/asciidoc/configuration.adoc

@@ -6,7 +6,12 @@
 [[configuration-uris]]
 === Documented URIs
 
-The default configuration for URIs documented by Spring REST Docs is:
+NOTE: As REST Assured tests a service by making actual HTTP requests, the documented
+URIs cannot be customized in this way. You should use the
+<<customizing-requests-and-responses-preprocessors-modify-uris, REST-Assured specific
+preprocessor>> instead.
+
+When using MockMvc, the default configuration for URIs documented by Spring REST Docs is:
 
 |===
 |Setting |Default
@@ -21,12 +26,12 @@ The default configuration for URIs documented by Spring REST Docs is:
 |`8080`
 |===
 
-This configuration is applied by `RestDocumentationMockMvcConfigurer`. You can use its API
+This configuration is applied by `MockMvcRestDocumentationConfigurer`. You can use its API
 to change one or more of the defaults to suit your needs:
 
 [source,java,indent=0]
 ----
-include::{examples-dir}/com/example/CustomUriConfiguration.java[tags=custom-uri-configuration]
+include::{examples-dir}/com/example/mockmvc/CustomUriConfiguration.java[tags=custom-uri-configuration]
 ----
 
 TIP: To configure a request's context path, use the `contextPath` method on
@@ -38,12 +43,19 @@ TIP: To configure a request's context path, use the `contextPath` method on
 === Snippet encoding
 
 The default encoding used by Asciidoctor is `UTF-8`. Spring REST Docs adopts the same
-default for the snippets that it generates. If you require an encoding other than `UTF-8`,
-use `RestDocumentationMockMvcConfigurer` to configure it:
+default for the snippets that it generates. You can change the default snippet encoding
+using the `RestDocumentationConfigurer` API. For example, to use `ISO-8859-1`:
 
-[source,java,indent=0]
+[source,java,indent=0,role="primary"]
+.MockMvc
+----
+include::{examples-dir}/com/example/mockmvc/CustomEncoding.java[tags=custom-encoding]
+----
+
+[source,java,indent=0,role="secondary"]
+.REST Assured
 ----
-include::{examples-dir}/com/example/CustomEncoding.java[tags=custom-encoding]
+include::{examples-dir}/com/example/restassured/CustomEncoding.java[tags=custom-encoding]
 ----
 
 
@@ -57,11 +69,18 @@ Three snippets are produced by default:
 - `http-request`
 - `http-response`
 
-This default configuration is applied by `RestDocumentationMockMvcConfigurer`. You can use
-its API to change the configuration. For example, to only produce the `curl-request`
+You can change the default snippet configuration during setup using the
+`RestDocumentationConfigurer` API. For example, to only produce the `curl-request`
 snippet by default:
 
-[source,java,indent=0]
+[source,java,indent=0,role="primary"]
+.MockMvc
+----
+include::{examples-dir}/com/example/mockmvc/CustomDefaultSnippets.java[tags=custom-default-snippets]
+----
+
+[source,java,indent=0,role="secondary"]
+.REST Assured
 ----
-include::{examples-dir}/com/example/CustomDefaultSnippetsConfiguration.java[tags=custom-default-snippets]
+include::{examples-dir}/com/example/restassured/CustomDefaultSnippets.java[tags=custom-default-snippets]
 ----

docs/src/docs/asciidoc/customizing-requests-and-responses.adoc

@@ -10,9 +10,18 @@ and/or an `OperationResponsePreprocessor`. Instances can be obtained using the
 static `preprocessRequest` and `preprocessResponse` methods on `Preprocessors`. For
 example:
 
-[source,java,indent=0]
+[source,java,indent=0,role="primary"]
+.MockMvc
 ----
-include::{examples-dir}/com/example/PerTestPreprocessing.java[tags=preprocessing]
+include::{examples-dir}/com/example/mockmvc/PerTestPreprocessing.java[tags=preprocessing]
+----
+<1> Apply a request preprocessor that will remove the header named `Foo`.
+<2> Apply a response preprocessor that will pretty print its content.
+
+[source,java,indent=0,role="secondary"]
+.REST Assured
+----
+include::{examples-dir}/com/example/restassured/PerTestPreprocessing.java[tags=preprocessing]
 ----
 <1> Apply a request preprocessor that will remove the header named `Foo`.
 <2> Apply a response preprocessor that will pretty print its content.
@@ -22,25 +31,44 @@ so by configuring the preprocessors in your `@Before` method and using the
 <<documentating-your-api-parameterized-output-directories, support for parameterized
 output directories>>:
 
-[source,java,indent=0]
+[source,java,indent=0,role="primary"]
+.MockMvc
 ----
-include::{examples-dir}/com/example/EveryTestPreprocessing.java[tags=setup]
+include::{examples-dir}/com/example/mockmvc/EveryTestPreprocessing.java[tags=setup]
 ----
-<1> Create the `RestDocumentationResultHandler`, configured to preprocess the request
+<1> Create a `RestDocumentationResultHandler`, configured to preprocess the request
 	and response.
-<2> Create the `MockMvc` instance, configured to always call the documentation result
+<2> Create a `MockMvc` instance, configured to always call the documentation result
 	handler.
 
-Then, in each test, the `RestDocumentationResultHandler` can be configured with anything
-test-specific. For example:
+[source,java,indent=0,role="secondary"]
+.REST Assured
+----
+include::{examples-dir}/com/example/restassured/EveryTestPreprocessing.java[tags=setup]
+----
+<1> Create a `RestDocumentationFilter`, configured to preprocess the request
+	and response.
+<2> Create a `RequestSpecification` instance, configured to always call the documentation
+	filter.
+
+Then, in each test, any configuration specific to that test can be performed. For example:
+
+[source,java,indent=0,role="primary"]
+.MockMvc
+----
+include::{examples-dir}/com/example/mockmvc/EveryTestPreprocessing.java[tags=use]
+----
+<1> Document the links specific to the resource that is being tested
+<2> The request and response will be preprocessed due to the use of `alwaysDo` above.
 
-[source,java,indent=0]
+[source,java,indent=0,role="secondary"]
+.REST Assured
 ----
-include::{examples-dir}/com/example/EveryTestPreprocessing.java[tags=use]
+include::{examples-dir}/com/example/restassured/EveryTestPreprocessing.java[tags=use]
 ----
 <1> Document the links specific to the resource that is being tested
-<2> The `perform` call will automatically produce the documentation snippets due to the
-	use of `alwaysDo` above.
+<2> The request and response will be preprocessed due to the configuration of the
+`RequestSpecification` in the `setUp` method.
 
 Various built in preprocessors, including those illustrated above, are available via the
 static methods on `Preprocessors`. See <<Preprocessors, below>> for further details.
@@ -86,6 +114,20 @@ from the request or response.
 replacing content in a request or response. Any occurrences of a regular expression are
 replaced.
 
+
+
+[[customizing-requests-and-responses-preprocessors-modify-uris]]
+==== Modifying URIs
+
+TIP: If you are using MockMvc, URIs should be customized by <<configuration-uris, changing
+the configuration>>.
+
+`modifyUris` on `RestAssuredPreprocessors` can be used to modify any URIs in a request
+or a response. When using REST Assured, this allows you to customize the URIs that appear
+in the documentation while testing a local instance of the service.
+
+
+
 [[customizing-requests-and-responses-preprocessors-writing-your-own]]
 ==== Writing your own preprocessor