Polish "Add auto-configuration for REST Docs with REST Assured"

Closes gh-9643

spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc

@@ -6279,8 +6279,20 @@ A list of the auto-configuration that is enabled by `@RestClientTest` can be
 [[boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs]]
 ==== Auto-configured Spring REST Docs tests
 The `@AutoConfigureRestDocs` annotation can be used if you want to use Spring REST Docs
-in your tests. It will automatically configure `MockMvc` to use Spring REST Docs and
-remove the need for Spring REST Docs' JUnit rule.
+in your tests with Mock MVC or REST Assured. It removes the need for Spring REST Docs'
+JUnit rule.
+
+`@AutoConfigureRestDocs` can be used to override the default output directory
+(`target/generated-snippets` if you are using Maven or `build/generated-snippets` if you
+are using Gradle). It can also be used to configure the host, scheme, and port that will
+appear in any documented URIs.
+
+[[boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs-mock-mvc]]
+===== Auto-configured Spring REST Docs tests with Mock MVC
+
+`@AutoConfigureRestDocs` customizes the `MockMvc` bean to use Spring REST Docs, Inject it
+using `@Autowired` and use it in your tests as you normally would when using Mock MVC and
+Spring REST Docs:
 
 [source,java,indent=0]
 ----
@@ -6315,11 +6327,9 @@ remove the need for Spring REST Docs' JUnit rule.
 	}
 ----
 
-`@AutoConfigureRestDocs` can be used to override the default output directory
-(`target/generated-snippets` if you are using Maven or `build/generated-snippets` if you
-are using Gradle). It can also be used to configure the host, scheme, and port that will
-appear in any documented URIs. If you require more control over Spring REST Docs'
-configuration a `RestDocsMockMvcConfigurationCustomizer` bean can be used:
+If you require more control over Spring REST Docs' configuration than offered by the
+attributes of `@AutoConfigureRestDocs`, a `RestDocsMockMvcConfigurationCustomizer` bean
+can be used:
 
 [source,java,indent=0]
 ----
@@ -6355,6 +6365,29 @@ automatically generate the default snippets:
 
 
 
+[[boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs-rest-assured]]
+===== Auto-configured Spring REST Docs tests with REST Assured
+
+`@AutoConfigureRestDocs` makes a `RequestSpecification` bean, preconfigured to use Spring REST
+Docs, available to your tests. Inject it using `@Autowired` and use it in your tests as you
+normally would when using REST Assured and Spring REST Docs:
+
+[source,java,indent=0]
+----
+include::{code-examples}/test/autoconfigure/restdocs/restassured/UserDocumentationTests.java[tag=source]
+----
+
+If you require more control over Spring REST Docs' configuration than offered by the
+attributes of `@AutoConfigureRestDocs`, a `RestDocsRestAssuredConfigurationCustomizer`
+bean can be used:
+
+[source,java,indent=0]
+----
+include::{code-examples}/test/autoconfigure/restdocs/restassured/AdvancedConfigurationExample.java[tag=configuration]
+----
+
+
+
 [[boot-features-testing-spring-boot-applications-with-spock]]
 ==== Using Spock to test Spring Boot applications
 If you wish to use Spock to test a Spring Boot application you should add a dependency

spring-boot-docs/src/main/java/org/springframework/boot/test/autoconfigure/restdocs/restassured/AdvancedConfigurationExample.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2012-2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.test.autoconfigure.restdocs.restassured;
+
+import org.springframework.boot.test.autoconfigure.restdocs.RestDocsRestAssuredConfigurationCustomizer;
+import org.springframework.boot.test.context.TestConfiguration;
+import org.springframework.restdocs.restassured3.RestAssuredRestDocumentationConfigurer;
+import org.springframework.restdocs.templates.TemplateFormats;
+
+public class AdvancedConfigurationExample {
+
+	// tag::configuration[]
+	@TestConfiguration
+	public static class CustomizationConfiguration
+			implements RestDocsRestAssuredConfigurationCustomizer {
+
+		@Override
+		public void customize(RestAssuredRestDocumentationConfigurer configurer) {
+			configurer.snippets().withTemplateFormat(TemplateFormats.markdown());
+		}
+
+	}
+	// end::configuration[]
+
+}

spring-boot-docs/src/main/java/org/springframework/boot/test/autoconfigure/restdocs/restassured/UserDocumentationTests.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2012-2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.test.autoconfigure.restdocs.restassured;
+
+// tag::source[]
+import io.restassured.specification.RequestSpecification;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
+import org.springframework.boot.web.server.LocalServerPort;
+import org.springframework.test.context.junit4.SpringRunner;
+
+import static io.restassured.RestAssured.given;
+import static org.hamcrest.CoreMatchers.is;
+import static org.springframework.restdocs.restassured3.RestAssuredRestDocumentation.document;
+
+@RunWith(SpringRunner.class)
+@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
+@AutoConfigureRestDocs
+public class UserDocumentationTests {
+
+	@LocalServerPort
+	private int port;
+
+	@Autowired
+	private RequestSpecification documentationSpec;
+
+	@Test
+	public void listUsers() throws Exception {
+		given(this.documentationSpec).filter(document("list-users")).when()
+				.port(this.port).get("/").then().assertThat().statusCode(is(200));
+	}
+
+}
+// end::source[]