Provide test auto-configuration for Spring REST Docs

This commit introduces a new annotation, @AutoConfigureRestDocs,
which can be used to enable auto-configuration of Spring REST Docs.
The auto-configuration removes the need to use Spring REST Docs' JUnit
rule and will automatically configure MockMvc. Combined with the new
auto-configuration for MockMvc it allows a test class to be free of
boilerplate configuration:

@RunWith(SpringRunner.class)
@WebMvcTest
@AutoConfigureRestDocs(outputDir = "target/generated-snippets",
        uriScheme = "https", uriHost = "api.example.com",
        uriPort = 443)
public class ExampleDocumentationTests {

    @Autowired
    private MockMvc mvc;

    @Test
    public void documentIndex() {
        // …
    }

}

For more advanced customization a RestDocsMockMvcConfigurationCustomizer
bean can be used.

If a RestDocumentationResultHandler is found in the context, it will
be passed to the ConfigurableMockMvcBuilder's alwaysDo method as part
of its customization.

Closes gh-5563

spring-boot-test-autoconfigure/src/test/java/org/springframework/boot/test/autoconfigure/restdocs/ContentContainingCondition.java

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2012-2016 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;
+
+import java.io.File;
+import java.io.FileReader;
+import java.io.IOException;
+import java.io.Reader;
+
+import org.assertj.core.api.Condition;
+import org.assertj.core.description.TextDescription;
+
+import org.springframework.util.FileCopyUtils;
+
+/**
+ * A {@link Condition} to assert that a file's contents contain a given string.
+ *
+ * @author Andy Wilkinson
+ */
+class ContentContainingCondition extends Condition<File> {
+
+	private final String toContain;
+
+	ContentContainingCondition(String toContain) {
+		super(new TextDescription("content containing %s", toContain));
+		this.toContain = toContain;
+	}
+
+	@Override
+	public boolean matches(File value) {
+		Reader reader = null;
+		try {
+			reader = new FileReader(value);
+			String content = FileCopyUtils.copyToString(new FileReader(value));
+			System.out.println(content);
+			return content.contains(this.toContain);
+		}
+		catch (IOException ex) {
+			throw new IllegalStateException(ex);
+		}
+		finally {
+			if (reader != null) {
+				try {
+					reader.close();
+				}
+				catch (IOException ex) {
+					// Ignore
+				}
+			}
+		}
+	}
+
+}

spring-boot-test-autoconfigure/src/test/java/org/springframework/boot/test/autoconfigure/restdocs/RestDocsAutoConfigurationAdvancedConfigurationIntegrationTests.java

@@ -0,0 +1,95 @@
+/*
+ * Copyright 2012-2016 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;
+
+import java.io.File;
+
+import org.assertj.core.api.Condition;
+import org.junit.Before;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
+import org.springframework.boot.test.context.TestConfiguration;
+import org.springframework.context.annotation.Bean;
+import org.springframework.restdocs.mockmvc.MockMvcRestDocumentation;
+import org.springframework.restdocs.mockmvc.MockMvcRestDocumentationConfigurer;
+import org.springframework.restdocs.mockmvc.RestDocumentationResultHandler;
+import org.springframework.restdocs.templates.TemplateFormats;
+import org.springframework.test.context.junit4.SpringRunner;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.util.FileSystemUtils;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.linkWithRel;
+import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.links;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+
+/**
+ * @author Andy Wilkinson
+ */
+@RunWith(SpringRunner.class)
+@WebMvcTest(RestDocsTestController.class)
+@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
+public class RestDocsAutoConfigurationAdvancedConfigurationIntegrationTests {
+
+	@Before
+	public void deleteSnippets() {
+		FileSystemUtils.deleteRecursively(new File("target/generated-snippets"));
+	}
+
+	@Autowired
+	private MockMvc mvc;
+
+	@Autowired
+	private RestDocumentationResultHandler document;
+
+	@Test
+	public void snippetGeneration() throws Exception {
+		this.document.snippets(links(
+				linkWithRel("self").description("Canonical location of this resource")));
+		this.mvc.perform(get("/"));
+		File defaultSnippetsDir = new File(
+				"target/generated-snippets/snippet-generation");
+		assertThat(defaultSnippetsDir).exists();
+		assertThat(new File(defaultSnippetsDir, "curl-request.md"))
+				.has(contentContaining("'http://localhost:8080/'"));
+		assertThat(new File(defaultSnippetsDir, "links.md")).isFile();
+	}
+
+	private Condition<File> contentContaining(String toContain) {
+		return new ContentContainingCondition(toContain);
+	}
+
+	@TestConfiguration
+	public static class CustomizationConfiguration
+			implements RestDocsMockMvcConfigurationCustomizer {
+
+		@Bean
+		public RestDocumentationResultHandler restDocumentation() {
+			return MockMvcRestDocumentation.document("{method-name}");
+		}
+
+		@Override
+		public void customize(MockMvcRestDocumentationConfigurer configurer) {
+			configurer.snippets().withTemplateFormat(TemplateFormats.markdown());
+		}
+
+	}
+
+}

spring-boot-test-autoconfigure/src/test/java/org/springframework/boot/test/autoconfigure/restdocs/RestDocsAutoConfigurationIntegrationTests.java

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2012-2016 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;
+
+import java.io.File;
+
+import org.assertj.core.api.Condition;
+import org.junit.Before;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
+import org.springframework.test.context.junit4.SpringRunner;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.util.FileSystemUtils;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+
+/**
+ * Tests for {@link RestDocsAutoConfiguration}.
+ *
+ * @author Andy Wilkinson
+ */
+@RunWith(SpringRunner.class)
+@WebMvcTest
+@AutoConfigureRestDocs(outputDir = "target/generated-snippets", uriScheme = "https", uriHost = "api.example.com", uriPort = 443)
+public class RestDocsAutoConfigurationIntegrationTests {
+
+	@Before
+	public void deleteSnippets() {
+		FileSystemUtils.deleteRecursively(new File("target/generated-snippets"));
+	}
+
+	@Autowired
+	private MockMvc mvc;
+
+	@Test
+	public void defaultSnippetsAreWritten() throws Exception {
+		this.mvc.perform(get("/")).andDo(document("default-snippets"));
+		File defaultSnippetsDir = new File("target/generated-snippets/default-snippets");
+		assertThat(defaultSnippetsDir).exists();
+		assertThat(new File(defaultSnippetsDir, "curl-request.adoc"))
+				.has(contentContaining("'https://api.example.com/'"));
+		assertThat(new File(defaultSnippetsDir, "http-request.adoc"))
+				.has(contentContaining("api.example.com"));
+		assertThat(new File(defaultSnippetsDir, "http-response.adoc")).isFile();
+	}
+
+	private Condition<File> contentContaining(String toContain) {
+		return new ContentContainingCondition(toContain);
+	}
+
+}

spring-boot-test-autoconfigure/src/test/java/org/springframework/boot/test/autoconfigure/restdocs/RestDocsTestApplication.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2012-2016 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;
+
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * Test application used with {@link AutoConfigureRestDocs} tests.
+ *
+ * @author Andy Wilkinson
+ */
+@SpringBootApplication
+public class RestDocsTestApplication {
+
+}

spring-boot-test-autoconfigure/src/test/java/org/springframework/boot/test/autoconfigure/restdocs/RestDocsTestController.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2012-2016 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;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import org.springframework.hateoas.MediaTypes;
+import org.springframework.hateoas.mvc.ControllerLinkBuilder;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.ResponseBody;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+public class RestDocsTestController {
+
+	@ResponseBody
+	@RequestMapping(path = "/", produces = MediaTypes.HAL_JSON_VALUE)
+	public Map<String, Object> index() {
+		Map<String, Object> response = new HashMap<String, Object>();
+		Map<String, String> links = new HashMap<String, String>();
+		links.put("self", ControllerLinkBuilder.linkTo(getClass()).toUri().toString());
+		response.put("_links", links);
+		return response;
+	}
+
+}