Add support for manually managing the RestDocumentationContext

In 1.0, the reliance on JUnit was more widespread than it should have
been. It should have been isolated to the JUnit TestRule implementation,
RestDocumentation. Unfortunately, RestDocumentation was also an argument
to MockMvcRestDocumentation.documentationConfiguration which made it
impossible to use Spring REST Docs without having JUnit on the
classpath.

This commit introduces JUnitRestDocumentation and
ManualRestDocumentation. The format is a direct replacement for
RestDocumentation which has been reworked to delegate to
JUnitRestDocumentation. The latter allows manual management of the
RestDocumentationContext, primarily for use with TestNG.

A new interface, RestDocumentationContextProvider, has been introduced.
It is implemented by RestDocumentation, JUnitRestDocumentation and
ManualRestDocumentation.
MockMvcRestDocumentation.documentationConfiguration has been overridden
to also accept a RestDocumentationContextProvider. The method that
accepts a RestDocumentation has been deprecated, as has
RestDocumentation itself.

The documentation has been updated to encourage the use of
JUnitRestDocumentation and a sample illustrating the use of Spring REST
Docs with TestNG has been added.

Closes gh-171

spring-restdocs-mockmvc/src/main/java/org/springframework/restdocs/mockmvc/MockMvcRestDocumentation.java

@@ -17,6 +17,7 @@
 package org.springframework.restdocs.mockmvc;
 
 import org.springframework.restdocs.RestDocumentation;
+import org.springframework.restdocs.RestDocumentationContextProvider;
 import org.springframework.restdocs.generate.RestDocumentationGenerator;
 import org.springframework.restdocs.operation.preprocess.OperationRequestPreprocessor;
 import org.springframework.restdocs.operation.preprocess.OperationResponsePreprocessor;
@@ -31,6 +32,7 @@ import org.springframework.test.web.servlet.setup.MockMvcConfigurer;
  *
  * @author Andy Wilkinson
  */
+@SuppressWarnings("deprecation")
 public abstract class MockMvcRestDocumentation {
 
 	private static final MockMvcRequestConverter REQUEST_CONVERTER = new MockMvcRequestConverter();
@@ -48,10 +50,26 @@ public abstract class MockMvcRestDocumentation {
 	 * @param restDocumentation the REST documentation
 	 * @return the configurer
 	 * @see ConfigurableMockMvcBuilder#apply(MockMvcConfigurer)
+	 * @deprecated Since 1.1 in favor of
+	 * {@link #documentationConfiguration(RestDocumentationContextProvider)}
 	 */
+	@Deprecated
 	public static MockMvcRestDocumentationConfigurer documentationConfiguration(
 			RestDocumentation restDocumentation) {
-		return new MockMvcRestDocumentationConfigurer(restDocumentation);
+		return documentationConfiguration((RestDocumentationContextProvider) restDocumentation);
+	}
+
+	/**
+	 * Provides access to a {@link MockMvcConfigurer} that can be used to configure a
+	 * {@link MockMvc} instance using the given {@code contextProvider}.
+	 *
+	 * @param contextProvider the context provider
+	 * @return the configurer
+	 * @see ConfigurableMockMvcBuilder#apply(MockMvcConfigurer)
+	 */
+	public static MockMvcRestDocumentationConfigurer documentationConfiguration(
+			RestDocumentationContextProvider contextProvider) {
+		return new MockMvcRestDocumentationConfigurer(contextProvider);
 	}
 
 	/**

spring-restdocs-mockmvc/src/main/java/org/springframework/restdocs/mockmvc/MockMvcRestDocumentationConfigurer.java

@@ -20,8 +20,8 @@ import java.util.HashMap;
 import java.util.Map;
 
 import org.springframework.mock.web.MockHttpServletRequest;
-import org.springframework.restdocs.RestDocumentation;
 import org.springframework.restdocs.RestDocumentationContext;
+import org.springframework.restdocs.RestDocumentationContextProvider;
 import org.springframework.restdocs.config.RestDocumentationConfigurer;
 import org.springframework.restdocs.generate.RestDocumentationGenerator;
 import org.springframework.test.web.servlet.request.RequestPostProcessor;
@@ -44,11 +44,10 @@ public class MockMvcRestDocumentationConfigurer
 
 	private final UriConfigurer uriConfigurer = new UriConfigurer(this);
 
-	private final RestDocumentation restDocumentation;
+	private final RestDocumentationContextProvider contextManager;
 
-	MockMvcRestDocumentationConfigurer(RestDocumentation restDocumentation) {
-		super();
-		this.restDocumentation = restDocumentation;
+	MockMvcRestDocumentationConfigurer(RestDocumentationContextProvider contextManager) {
+		this.contextManager = contextManager;
 	}
 
 	/**
@@ -64,7 +63,7 @@ public class MockMvcRestDocumentationConfigurer
 	@Override
 	public RequestPostProcessor beforeMockMvcCreated(
 			ConfigurableMockMvcBuilder<?> builder, WebApplicationContext context) {
-		return new ConfigurerApplyingRequestPostProcessor(this.restDocumentation);
+		return new ConfigurerApplyingRequestPostProcessor(this.contextManager);
 	}
 
 	@Override
@@ -80,15 +79,16 @@ public class MockMvcRestDocumentationConfigurer
 	private final class ConfigurerApplyingRequestPostProcessor implements
 			RequestPostProcessor {
 
-		private final RestDocumentation restDocumentation;
+		private final RestDocumentationContextProvider contextManager;
 
-		private ConfigurerApplyingRequestPostProcessor(RestDocumentation restDocumentation) {
-			this.restDocumentation = restDocumentation;
+		private ConfigurerApplyingRequestPostProcessor(
+				RestDocumentationContextProvider contextManager) {
+			this.contextManager = contextManager;
 		}
 
 		@Override
 		public MockHttpServletRequest postProcessRequest(MockHttpServletRequest request) {
-			RestDocumentationContext context = this.restDocumentation.beforeOperation();
+			RestDocumentationContext context = this.contextManager.beforeOperation();
 			Map<String, Object> configuration = new HashMap<>();
 			configuration.put(MockHttpServletRequest.class.getName(), request);
 			configuration

spring-restdocs-mockmvc/src/test/java/org/springframework/restdocs/mockmvc/MockMvcRestDocumentationConfigurerTests.java

@@ -22,7 +22,7 @@ import org.junit.Rule;
 import org.junit.Test;
 import org.springframework.hateoas.mvc.BasicLinkBuilder;
 import org.springframework.mock.web.MockHttpServletRequest;
-import org.springframework.restdocs.RestDocumentation;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.test.web.servlet.request.RequestPostProcessor;
 import org.springframework.web.context.request.RequestContextHolder;
 import org.springframework.web.context.request.ServletRequestAttributes;
@@ -43,7 +43,7 @@ public class MockMvcRestDocumentationConfigurerTests {
 	private MockHttpServletRequest request = new MockHttpServletRequest();
 
 	@Rule
-	public RestDocumentation restDocumentation = new RestDocumentation("test");
+	public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("test");
 
 	@Test
 	public void defaultConfiguration() {

spring-restdocs-mockmvc/src/test/java/org/springframework/restdocs/mockmvc/MockMvcRestDocumentationIntegrationTests.java

@@ -36,7 +36,7 @@ import org.springframework.http.HttpHeaders;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
-import org.springframework.restdocs.RestDocumentation;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.restdocs.hypermedia.Link;
 import org.springframework.restdocs.mockmvc.MockMvcRestDocumentationIntegrationTests.TestConfiguration;
 import org.springframework.test.context.ContextConfiguration;
@@ -96,7 +96,7 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
 public class MockMvcRestDocumentationIntegrationTests {
 
 	@Rule
-	public RestDocumentation restDocumentation = new RestDocumentation(
+	public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(
 			"build/generated-snippets");
 
 	@Autowired