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

build.gradle

@@ -162,6 +162,10 @@ samples {
 	restNotesSpringDataRest {
 		workingDir "$projectDir/samples/rest-notes-spring-data-rest"
 	}
+
+	testNg {
+		workingDir "$projectDir/samples/testng"
+	}
 }
 
 task api (type: Javadoc) {

docs/build.gradle

@@ -6,6 +6,8 @@ dependencies {
 	testCompile project(':spring-restdocs-mockmvc')
 	testCompile project(':spring-restdocs-restassured')
 	testCompile 'javax.validation:validation-api'
+	testCompile 'junit:junit'
+	testCompile 'org.testng:testng:6.9.10'
 }
 
 tasks.findByPath("artifactoryPublish")?.enabled = false

docs/src/docs/asciidoc/getting-started.adoc

@@ -203,7 +203,7 @@ from where it will be included in the jar file.
 
 [[getting-started-documentation-snippets]]
 === Generating documentation snippets
-Spring REST Docs uses JUnit and
+Spring REST Docs uses
 {spring-framework-docs}/#spring-mvc-test-framework[Spring's MVC Test framework] or
 http://www.rest-assured.io[REST Assured] to make requests to the service that you are
 documenting. It then produces documentation snippets for the request and the resulting
@@ -214,11 +214,18 @@ response.
 [[getting-started-documentation-snippets-setup]]
 ==== Setting up your tests
 
-The first step in generating documentation snippets is to declare a `public`
-`RestDocumentation` field that's annotated as a JUnit `@Rule`. The `RestDocumentation`
-rule is configured with the output directory into which generated snippets should be
-written. This output directory should match the snippets directory that you have
-configured in your `build.gradle` or `pom.xml` file.
+Exactly how you setup your tests depends on the test framework that you're using.
+Spring REST Docs provides first-class support for JUnit. Other frameworks, such as TestNG,
+are also supported although slightly more setup is required.
+
+[[getting-started-documentation-snippets-setup-junit]]
+===== Setting up your JUnit tests
+
+When using JUnit, the first step in generating documentation snippets is to declare a
+`public` `JUnitRestDocumentation` field that's annotated as a JUnit `@Rule`. The
+`JUnitRestDocumentation` rule is configured with the output directory into which generated
+snippets should be written. This output directory should match the snippets directory that
+you have configured in your `build.gradle` or `pom.xml` file.
 
 For Maven (`pom.xml` that will typically be `target/generated-snippets` and for
 Gradle (`build.gradle`) it will typically be `build/generated-snippets`:
@@ -227,14 +234,16 @@ Gradle (`build.gradle`) it will typically be `build/generated-snippets`:
 .Maven
 ----
 @Rule
-public RestDocumentation restDocumentation = new RestDocumentation("target/generated-snippets");
+public JUnitRestDocumentation restDocumentation =
+		new JUnitRestDocumentation("target/generated-snippets");
 ----
 
 [source,java,indent=0,role="secondary"]
 .Gradle
 ----
 @Rule
-public RestDocumentation restDocumentation = new RestDocumentation("build/generated-snippets");
+public JUnitRestDocumentation restDocumentation =
+		new JUnitRestDocumentation("build/generated-snippets");
 ----
 
 Next, provide an `@Before` method to configure MockMvc or REST Assured:
@@ -263,6 +272,54 @@ configuration. Refer to the <<configuration, configuration section>> for more in
 
 
 
+===== Setting up your tests without JUnit
+[[getting-started-documentation-snippets-setup-manual]]
+
+The configuration when JUnit is not being used is largely similar to when it is being
+used. This section describes the key differences. The {samples}/testng[TestNG sample] also
+illustrates the approach.
+
+The first difference is that `ManualRestDocumentation` should be used in place of
+`JUnitRestDocumentation` and there's no need for the `@Rule` annotation:
+
+[source,java,indent=0,role="primary"]
+.Maven
+----
+private ManualRestDocumentation restDocumentation =
+		new ManualRestDocumentation("target/generated-snippets");
+----
+
+[source,java,indent=0,role="secondary"]
+.Gradle
+----
+private ManualRestDocumentation restDocumentation =
+		new ManualRestDocumentation("build/generated-snippets");
+----
+
+Secondly, `ManualRestDocumentation.beforeTest(Class, String)`
+must be called before each test. This can be done as part of the method that is
+configuring MockMVC or REST Assured:
+
+[source,java,indent=0,role="primary"]
+.MockMvc
+----
+include::{examples-dir}/com/example/mockmvc/ExampleApplicationTestNgTests.java[tags=setup]
+----
+
+[source,java,indent=0,role="secondary"]
+.REST Assured
+----
+include::{examples-dir}/com/example/restassured/ExampleApplicationTestNgTests.java[tags=setup]
+----
+
+Lastly, `ManualRestDocumentation.afterTest` must be called after each test. For example,
+with TestNG:
+
+[source,java,indent=0]
+----
+include::{examples-dir}/com/example/restassured/ExampleApplicationTestNgTests.java[tags=teardown]
+----
+
 [[getting-started-documentation-snippets-invoking-the-service]]
 ==== Invoking the RESTful service
 

docs/src/test/java/com/example/mockmvc/CustomDefaultSnippets.java

@@ -16,21 +16,22 @@
 
 package com.example.mockmvc;
 
-import static org.springframework.restdocs.curl.CurlDocumentation.curlRequest;
-import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
-
 import org.junit.Before;
 import org.junit.Rule;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.restdocs.RestDocumentation;
 import org.springframework.test.web.servlet.MockMvc;
 import org.springframework.test.web.servlet.setup.MockMvcBuilders;
 import org.springframework.web.context.WebApplicationContext;
 
+import static org.springframework.restdocs.curl.CurlDocumentation.curlRequest;
+import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
+
 public class CustomDefaultSnippets {
 
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation("build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build");
 
 	@Autowired
 	private WebApplicationContext context;

docs/src/test/java/com/example/mockmvc/CustomEncoding.java

@@ -16,20 +16,21 @@
 
 package com.example.mockmvc;
 
-import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
-
 import org.junit.Before;
 import org.junit.Rule;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.restdocs.RestDocumentation;
 import org.springframework.test.web.servlet.MockMvc;
 import org.springframework.test.web.servlet.setup.MockMvcBuilders;
 import org.springframework.web.context.WebApplicationContext;
 
+import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
+
 public class CustomEncoding {
 
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation("build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build");
 
 	@Autowired
 	private WebApplicationContext context;

docs/src/test/java/com/example/mockmvc/CustomFormat.java

@@ -16,21 +16,22 @@
 
 package com.example.mockmvc;
 
-import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
-
 import org.junit.Before;
 import org.junit.Rule;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.restdocs.RestDocumentation;
 import org.springframework.restdocs.templates.TemplateFormats;
 import org.springframework.test.web.servlet.MockMvc;
 import org.springframework.test.web.servlet.setup.MockMvcBuilders;
 import org.springframework.web.context.WebApplicationContext;
 
+import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
+
 public class CustomFormat {
 
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation("build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build");
 
 	@Autowired
 	private WebApplicationContext context;

docs/src/test/java/com/example/mockmvc/CustomUriConfiguration.java

@@ -16,20 +16,21 @@
 
 package com.example.mockmvc;
 
-import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
-
 import org.junit.Before;
 import org.junit.Rule;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.restdocs.RestDocumentation;
 import org.springframework.test.web.servlet.MockMvc;
 import org.springframework.test.web.servlet.setup.MockMvcBuilders;
 import org.springframework.web.context.WebApplicationContext;
 
+import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
+
 public class CustomUriConfiguration {
 
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation("build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build");
 
 	@Autowired
 	private WebApplicationContext context;

docs/src/test/java/com/example/mockmvc/EveryTestPreprocessing.java

@@ -18,6 +18,7 @@ package com.example.mockmvc;
 
 import org.junit.Before;
 import org.junit.Rule;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.restdocs.RestDocumentation;
 import org.springframework.restdocs.mockmvc.RestDocumentationResultHandler;
 import org.springframework.test.web.servlet.MockMvc;
@@ -38,7 +39,7 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
 public class EveryTestPreprocessing {
 
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation(
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(
 			"target/generated-snippets");
 
 	private WebApplicationContext context;

docs/src/test/java/com/example/mockmvc/ExampleApplicationTestNgTests.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2014-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 com.example.mockmvc;
+
+import java.lang.reflect.Method;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.restdocs.ManualRestDocumentation;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.setup.MockMvcBuilders;
+import org.springframework.web.context.WebApplicationContext;
+import org.testng.annotations.AfterMethod;
+import org.testng.annotations.BeforeMethod;
+
+import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
+
+public class ExampleApplicationTestNgTests {
+
+	public final ManualRestDocumentation restDocumentation = new ManualRestDocumentation(
+			"target/generated-snippets");
+	// tag::setup[]
+	@Autowired
+	private WebApplicationContext context;
+
+	private MockMvc mockMvc;
+
+	@BeforeMethod
+	public void setUp(Method method) {
+		this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
+				.apply(documentationConfiguration(this.restDocumentation))
+				.build();
+		this.restDocumentation.beforeTest(getClass(), method.getName());
+	}
+
+	// end::setup[]
+
+	// tag::teardown[]
+	@AfterMethod
+	public void tearDown() {
+		this.restDocumentation.afterTest();
+	}
+	// end::teardown[]
+
+}

docs/src/test/java/com/example/mockmvc/ExampleApplicationTests.java

@@ -19,7 +19,7 @@ package com.example.mockmvc;
 import org.junit.Before;
 import org.junit.Rule;
 import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.restdocs.RestDocumentation;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.test.web.servlet.MockMvc;
 import org.springframework.test.web.servlet.setup.MockMvcBuilders;
 import org.springframework.web.context.WebApplicationContext;
@@ -29,7 +29,7 @@ import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.docu
 public class ExampleApplicationTests {
 
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation(
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(
 			"target/generated-snippets");
 	// tag::setup[]
 	@Autowired
@@ -44,4 +44,5 @@ public class ExampleApplicationTests {
 				.build();
 	}
 	// end::setup[]
+
 }

docs/src/test/java/com/example/mockmvc/ParameterizedOutput.java

@@ -18,6 +18,7 @@ package com.example.mockmvc;
 
 import org.junit.Before;
 import org.junit.Rule;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.restdocs.RestDocumentation;
 import org.springframework.test.web.servlet.MockMvc;
 import org.springframework.test.web.servlet.setup.MockMvcBuilders;
@@ -29,7 +30,7 @@ import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.docu
 public class ParameterizedOutput {
 
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation("build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build");
 
 	private MockMvc mockMvc;
 

docs/src/test/java/com/example/mockmvc/Payload.java

@@ -32,7 +32,7 @@ import org.springframework.test.web.servlet.MockMvc;
 
 public class Payload {
 
-private MockMvc mockMvc;
+	private MockMvc mockMvc;
 
 	public void response() throws Exception {
 		// tag::response[]

docs/src/test/java/com/example/restassured/CustomDefaultSnippets.java

@@ -18,6 +18,7 @@ package com.example.restassured;
 
 import org.junit.Before;
 import org.junit.Rule;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.restdocs.RestDocumentation;
 
 import com.jayway.restassured.builder.RequestSpecBuilder;
@@ -29,9 +30,9 @@ import static org.springframework.restdocs.restassured.RestAssuredRestDocumentat
 public class CustomDefaultSnippets {
 
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation("build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build");
 
-	RequestSpecification spec;
+	private RequestSpecification spec;
 
 	@Before
 	public void setUp() {

docs/src/test/java/com/example/restassured/CustomEncoding.java

@@ -18,6 +18,7 @@ package com.example.restassured;
 
 import org.junit.Before;
 import org.junit.Rule;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.restdocs.RestDocumentation;
 
 import com.jayway.restassured.builder.RequestSpecBuilder;
@@ -28,7 +29,7 @@ import static org.springframework.restdocs.restassured.RestAssuredRestDocumentat
 public class CustomEncoding {
 
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation("build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build");
 
 	private RequestSpecification spec;
 

docs/src/test/java/com/example/restassured/CustomFormat.java

@@ -18,6 +18,7 @@ package com.example.restassured;
 
 import org.junit.Before;
 import org.junit.Rule;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.restdocs.RestDocumentation;
 import org.springframework.restdocs.templates.TemplateFormats;
 
@@ -29,7 +30,7 @@ import static org.springframework.restdocs.restassured.RestAssuredRestDocumentat
 public class CustomFormat {
 
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation("build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build");
 
 	private RequestSpecification spec;
 

docs/src/test/java/com/example/restassured/EveryTestPreprocessing.java

@@ -18,6 +18,7 @@ package com.example.restassured;
 
 import org.junit.Before;
 import org.junit.Rule;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.restdocs.RestDocumentation;
 import org.springframework.restdocs.restassured.RestDocumentationFilter;
 
@@ -38,7 +39,7 @@ import static org.springframework.restdocs.restassured.RestAssuredRestDocumentat
 public class EveryTestPreprocessing {
 
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation(
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(
 			"target/generated-snippets");
 
 	// tag::setup[]

docs/src/test/java/com/example/restassured/ExampleApplicationTestNgTests.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2014-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 com.example.restassured;
+
+import java.lang.reflect.Method;
+
+import org.springframework.restdocs.ManualRestDocumentation;
+import org.testng.annotations.AfterMethod;
+import org.testng.annotations.BeforeMethod;
+
+import com.jayway.restassured.builder.RequestSpecBuilder;
+import com.jayway.restassured.specification.RequestSpecification;
+
+import static org.springframework.restdocs.restassured.RestAssuredRestDocumentation.documentationConfiguration;
+
+public class ExampleApplicationTestNgTests {
+
+	private final ManualRestDocumentation restDocumentation = new ManualRestDocumentation(
+			"build/generated-snippets");
+
+	// tag::setup[]
+	private RequestSpecification spec;
+
+	@BeforeMethod
+	public void setUp(Method method) {
+		this.spec = new RequestSpecBuilder().addFilter(
+				documentationConfiguration(this.restDocumentation))
+				.build();
+		this.restDocumentation.beforeTest(getClass(), method.getName());
+	}
+
+	// end::setup[]
+
+	// tag::teardown[]
+	@AfterMethod
+	public void tearDown() {
+		this.restDocumentation.afterTest();
+	}
+	// end::teardown[]
+}

docs/src/test/java/com/example/restassured/ExampleApplicationTests.java

@@ -18,6 +18,7 @@ package com.example.restassured;
 
 import org.junit.Before;
 import org.junit.Rule;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.restdocs.RestDocumentation;
 
 import com.jayway.restassured.builder.RequestSpecBuilder;
@@ -28,7 +29,7 @@ import static org.springframework.restdocs.restassured.RestAssuredRestDocumentat
 public class ExampleApplicationTests {
 
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation(
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(
 			"build/generated-snippets");
 
 	// tag::setup[]

docs/src/test/java/com/example/restassured/ParameterizedOutput.java

@@ -18,6 +18,7 @@ package com.example.restassured;
 
 import org.junit.Before;
 import org.junit.Rule;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.restdocs.RestDocumentation;
 
 import com.jayway.restassured.builder.RequestSpecBuilder;
@@ -29,7 +30,7 @@ import static org.springframework.restdocs.restassured.RestAssuredRestDocumentat
 public class ParameterizedOutput {
 
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation(
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(
 			"build/generated-snippets");
 
 	private RequestSpecification spec;

samples/rest-notes-spring-data-rest/src/test/java/com/example/notes/ApiDocumentation.java

@@ -20,8 +20,8 @@ import static org.hamcrest.Matchers.is;
 import static org.hamcrest.Matchers.notNullValue;
 import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.linkWithRel;
 import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.links;
-import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
 import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
+import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.patch;
 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.post;
@@ -45,7 +45,7 @@ import org.junit.runner.RunWith;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.SpringApplicationConfiguration;
 import org.springframework.hateoas.MediaTypes;
-import org.springframework.restdocs.RestDocumentation;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.restdocs.payload.JsonFieldType;
 import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
 import org.springframework.test.context.web.WebAppConfiguration;
@@ -61,7 +61,7 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 public class ApiDocumentation {
 	
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation("target/generated-snippets");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("target/generated-snippets");
 
 	@Autowired
 	private NoteRepository noteRepository;

samples/rest-notes-spring-data-rest/src/test/java/com/example/notes/GettingStartedDocumentation.java

@@ -19,8 +19,8 @@ package com.example.notes;
 import static org.hamcrest.Matchers.hasSize;
 import static org.hamcrest.Matchers.is;
 import static org.hamcrest.Matchers.notNullValue;
-import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
 import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
+import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.patch;
 import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.post;
@@ -40,7 +40,7 @@ import org.junit.runner.RunWith;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.SpringApplicationConfiguration;
 import org.springframework.hateoas.MediaTypes;
-import org.springframework.restdocs.RestDocumentation;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
 import org.springframework.test.context.web.WebAppConfiguration;
 import org.springframework.test.web.servlet.MockMvc;
@@ -58,7 +58,7 @@ import com.jayway.jsonpath.JsonPath;
 public class GettingStartedDocumentation {
 	
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation("target/generated-snippets");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("target/generated-snippets");
 
 	@Autowired
 	private ObjectMapper objectMapper;

samples/rest-notes-spring-hateoas/src/test/java/com/example/notes/ApiDocumentation.java

@@ -51,7 +51,7 @@ import org.junit.runner.RunWith;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.SpringApplicationConfiguration;
 import org.springframework.hateoas.MediaTypes;
-import org.springframework.restdocs.RestDocumentation;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.restdocs.constraints.ConstraintDescriptions;
 import org.springframework.restdocs.mockmvc.RestDocumentationResultHandler;
 import org.springframework.restdocs.payload.FieldDescriptor;
@@ -71,7 +71,7 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 public class ApiDocumentation {
 	
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation("build/generated-snippets");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build/generated-snippets");
 	
 	private RestDocumentationResultHandler document; 
 

samples/rest-notes-spring-hateoas/src/test/java/com/example/notes/GettingStartedDocumentation.java

@@ -43,7 +43,7 @@ import org.junit.runner.RunWith;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.SpringApplicationConfiguration;
 import org.springframework.hateoas.MediaTypes;
-import org.springframework.restdocs.RestDocumentation;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
 import org.springframework.test.context.web.WebAppConfiguration;
 import org.springframework.test.web.servlet.MockMvc;
@@ -61,7 +61,7 @@ import com.jayway.jsonpath.JsonPath;
 public class GettingStartedDocumentation {
 	
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation("build/generated-snippets");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build/generated-snippets");
 
 	@Autowired
 	private ObjectMapper objectMapper;

samples/testng/build.gradle

@@ -0,0 +1,62 @@
+buildscript {
+	repositories {
+		mavenCentral()
+	}
+	dependencies {
+		classpath 'org.springframework.boot:spring-boot-gradle-plugin:1.2.7.RELEASE'
+	}
+}
+
+plugins {
+	id "org.asciidoctor.convert" version "1.5.3"
+}
+
+apply plugin: 'java'
+apply plugin: 'spring-boot'
+apply plugin: 'eclipse'
+
+repositories {
+	mavenLocal()
+	maven { url 'https://repo.spring.io/libs-snapshot' }
+	mavenCentral()
+}
+
+group = 'com.example'
+
+sourceCompatibility = 1.7
+targetCompatibility = 1.7
+
+ext {
+	snippetsDir = file('build/generated-snippets')
+	springRestdocsVersion = '1.1.0.BUILD-SNAPSHOT'
+}
+
+dependencies {
+	compile 'org.springframework.boot:spring-boot-starter-web'
+	testCompile('org.springframework:spring-test') {
+		exclude group: 'junit', module: 'junit;'
+	}
+	testCompile 'org.testng:testng:6.9.10'
+	testCompile "org.springframework.restdocs:spring-restdocs-mockmvc:$springRestdocsVersion"
+}
+
+test {
+	useTestNG()
+	outputs.dir snippetsDir
+}
+
+asciidoctor {
+	attributes 'snippets': snippetsDir
+	inputs.dir snippetsDir
+	dependsOn test
+}
+
+jar {
+	dependsOn asciidoctor
+	from ("${asciidoctor.outputDir}/html5") {
+		into 'static/docs'
+	}
+}
+
+eclipseJdt.onlyIf { false }
+cleanEclipseJdt.onlyIf { false }

samples/testng/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,6 @@
+#Thu Apr 16 12:33:24 BST 2015
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-2.3-bin.zip

samples/testng/gradlew

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+
+##############################################################################
+##
+##  Gradle start up script for UN*X
+##
+##############################################################################
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS=""
+
+APP_NAME="Gradle"
+APP_BASE_NAME=`basename "$0"`
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD="maximum"
+
+warn ( ) {
+    echo "$*"
+}
+
+die ( ) {
+    echo
+    echo "$*"
+    echo
+    exit 1
+}
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+case "`uname`" in
+  CYGWIN* )
+    cygwin=true
+    ;;
+  Darwin* )
+    darwin=true
+    ;;
+  MINGW* )
+    msys=true
+    ;;
+esac
+
+# For Cygwin, ensure paths are in UNIX format before anything is touched.
+if $cygwin ; then
+    [ -n "$JAVA_HOME" ] && JAVA_HOME=`cygpath --unix "$JAVA_HOME"`
+fi
+
+# Attempt to set APP_HOME
+# Resolve links: $0 may be a link
+PRG="$0"
+# Need this for relative symlinks.
+while [ -h "$PRG" ] ; do
+    ls=`ls -ld "$PRG"`
+    link=`expr "$ls" : '.*-> \(.*\)$'`
+    if expr "$link" : '/.*' > /dev/null; then
+        PRG="$link"
+    else
+        PRG=`dirname "$PRG"`"/$link"
+    fi
+done
+SAVED="`pwd`"
+cd "`dirname \"$PRG\"`/" >&-
+APP_HOME="`pwd -P`"
+cd "$SAVED" >&-
+
+CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+        # IBM's JDK on AIX uses strange locations for the executables
+        JAVACMD="$JAVA_HOME/jre/sh/java"
+    else
+        JAVACMD="$JAVA_HOME/bin/java"
+    fi
+    if [ ! -x "$JAVACMD" ] ; then
+        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+else
+    JAVACMD="java"
+    which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+fi
+
+# Increase the maximum file descriptors if we can.
+if [ "$cygwin" = "false" -a "$darwin" = "false" ] ; then
+    MAX_FD_LIMIT=`ulimit -H -n`
+    if [ $? -eq 0 ] ; then
+        if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then
+            MAX_FD="$MAX_FD_LIMIT"
+        fi
+        ulimit -n $MAX_FD
+        if [ $? -ne 0 ] ; then
+            warn "Could not set maximum file descriptor limit: $MAX_FD"
+        fi
+    else
+        warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT"
+    fi
+fi
+
+# For Darwin, add options to specify how the application appears in the dock
+if $darwin; then
+    GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\""
+fi
+
+# For Cygwin, switch paths to Windows format before running java
+if $cygwin ; then
+    APP_HOME=`cygpath --path --mixed "$APP_HOME"`
+    CLASSPATH=`cygpath --path --mixed "$CLASSPATH"`
+
+    # We build the pattern for arguments to be converted via cygpath
+    ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null`
+    SEP=""
+    for dir in $ROOTDIRSRAW ; do
+        ROOTDIRS="$ROOTDIRS$SEP$dir"
+        SEP="|"
+    done
+    OURCYGPATTERN="(^($ROOTDIRS))"
+    # Add a user-defined pattern to the cygpath arguments
+    if [ "$GRADLE_CYGPATTERN" != "" ] ; then
+        OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)"
+    fi
+    # Now convert the arguments - kludge to limit ourselves to /bin/sh
+    i=0
+    for arg in "$@" ; do
+        CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -`
+        CHECK2=`echo "$arg"|egrep -c "^-"`                                 ### Determine if an option
+
+        if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then                    ### Added a condition
+            eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"`
+        else
+            eval `echo args$i`="\"$arg\""
+        fi
+        i=$((i+1))
+    done
+    case $i in
+        (0) set -- ;;
+        (1) set -- "$args0" ;;
+        (2) set -- "$args0" "$args1" ;;
+        (3) set -- "$args0" "$args1" "$args2" ;;
+        (4) set -- "$args0" "$args1" "$args2" "$args3" ;;
+        (5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;;
+        (6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;;
+        (7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;;
+        (8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;;
+        (9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;;
+    esac
+fi
+
+# Split up the JVM_OPTS And GRADLE_OPTS values into an array, following the shell quoting and substitution rules
+function splitJvmOpts() {
+    JVM_OPTS=("$@")
+}
+eval splitJvmOpts $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS
+JVM_OPTS[${#JVM_OPTS[*]}]="-Dorg.gradle.appname=$APP_BASE_NAME"
+
+exec "$JAVACMD" "${JVM_OPTS[@]}" -classpath "$CLASSPATH" org.gradle.wrapper.GradleWrapperMain "$@"

samples/testng/gradlew.bat

@@ -0,0 +1,90 @@
+@if "%DEBUG%" == "" @echo off
+@rem ##########################################################################
+@rem
+@rem  Gradle startup script for Windows
+@rem
+@rem ##########################################################################
+
+@rem Set local scope for the variables with windows NT shell
+if "%OS%"=="Windows_NT" setlocal
+
+@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+set DEFAULT_JVM_OPTS=
+
+set DIRNAME=%~dp0
+if "%DIRNAME%" == "" set DIRNAME=.
+set APP_BASE_NAME=%~n0
+set APP_HOME=%DIRNAME%
+
+@rem Find java.exe
+if defined JAVA_HOME goto findJavaFromJavaHome
+
+set JAVA_EXE=java.exe
+%JAVA_EXE% -version >NUL 2>&1
+if "%ERRORLEVEL%" == "0" goto init
+
+echo.
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+echo.
+echo Please set the JAVA_HOME variable in your environment to match the
+echo location of your Java installation.
+
+goto fail
+
+:findJavaFromJavaHome
+set JAVA_HOME=%JAVA_HOME:"=%
+set JAVA_EXE=%JAVA_HOME%/bin/java.exe
+
+if exist "%JAVA_EXE%" goto init
+
+echo.
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
+echo.
+echo Please set the JAVA_HOME variable in your environment to match the
+echo location of your Java installation.
+
+goto fail
+
+:init
+@rem Get command-line arguments, handling Windowz variants
+
+if not "%OS%" == "Windows_NT" goto win9xME_args
+if "%@eval[2+2]" == "4" goto 4NT_args
+
+:win9xME_args
+@rem Slurp the command line arguments.
+set CMD_LINE_ARGS=
+set _SKIP=2
+
+:win9xME_args_slurp
+if "x%~1" == "x" goto execute
+
+set CMD_LINE_ARGS=%*
+goto execute
+
+:4NT_args
+@rem Get arguments from the 4NT Shell from JP Software
+set CMD_LINE_ARGS=%$
+
+:execute
+@rem Setup the command line
+
+set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
+
+@rem Execute Gradle
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %CMD_LINE_ARGS%
+
+:end
+@rem End local scope for the variables with windows NT shell
+if "%ERRORLEVEL%"=="0" goto mainEnd
+
+:fail
+rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
+rem the _cmd.exe /c_ return code!
+if  not "" == "%GRADLE_EXIT_CONSOLE%" exit 1
+exit /b 1
+
+:mainEnd
+if "%OS%"=="Windows_NT" endlocal
+
+:omega

samples/testng/src/docs/asciidoc/index.adoc

@@ -0,0 +1,21 @@
+= Spring REST Docs TestNG Sample
+Andy Wilkinson;
+:doctype: book
+:icons: font
+:source-highlighter: highlightjs
+
+This sample application demonstrates how to use Spring REST Docs with TestNG.
+`SampleTestNgApplication` makes a call to a very simple service and produces three
+documentation snippets.
+
+One showing how to make a request using cURL:
+
+include::{snippets}/sample/curl-request.adoc[]
+
+One showing the HTTP request:
+
+include::{snippets}/sample/http-request.adoc[]
+
+And one showing the HTTP response:
+
+include::{snippets}/sample/http-response.adoc[]

samples/testng/src/main/java/com/example/testng/SampleTestNgApplication.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2014-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 com.example.testng;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@SpringBootApplication
+public class SampleTestNgApplication {
+
+	public static void main(String[] args) {
+		new SpringApplication(SampleTestNgApplication.class).run(args);
+	}
+
+	@RestController
+	private static class SampleController {
+
+		@RequestMapping("/")
+		public String index() {
+			return "Hello, World";
+		}
+
+	}
+
+}

samples/testng/src/test/java/com/example/testng/SampleTestNgApplicationTests.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2014-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 com.example.testng;
+
+import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
+import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+import java.lang.reflect.Method;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.SpringApplicationConfiguration;
+import org.springframework.restdocs.ManualRestDocumentation;
+import org.springframework.test.context.testng.AbstractTestNGSpringContextTests;
+import org.springframework.test.context.web.WebAppConfiguration;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.setup.MockMvcBuilders;
+import org.springframework.web.context.WebApplicationContext;
+import org.testng.annotations.AfterMethod;
+import org.testng.annotations.BeforeMethod;
+import org.testng.annotations.Test;
+
+@SpringApplicationConfiguration(classes=SampleTestNgApplication.class)
+@WebAppConfiguration
+public class SampleTestNgApplicationTests extends AbstractTestNGSpringContextTests {
+
+	private final ManualRestDocumentation restDocumentation = new ManualRestDocumentation("build/generated-snippets");
+
+	@Autowired
+	private WebApplicationContext context;
+
+	private MockMvc mockMvc;
+
+	@BeforeMethod
+	public void setUp(Method method) {
+		this.mockMvc = MockMvcBuilders.webAppContextSetup(context)
+				.apply(documentationConfiguration(this.restDocumentation)).build();
+		this.restDocumentation.beforeTest(getClass(), method.getName());
+	}
+
+	@AfterMethod
+	public void tearDown() {
+		this.restDocumentation.afterTest();
+	}
+
+	@Test
+	public void sample() throws Exception {
+		this.mockMvc.perform(get("/"))
+				.andExpect(status().isOk())
+				.andDo(document("sample"));
+	}
+
+}

spring-restdocs-core/build.gradle

@@ -26,14 +26,14 @@ task jmustacheRepackJar(type: Jar) { repackJar ->
 
 dependencies {
 	compile 'com.fasterxml.jackson.core:jackson-databind'
-	compile 'junit:junit'
 	compile 'org.springframework:spring-webmvc'
 	compile 'javax.servlet:javax.servlet-api'
 	compile files(jmustacheRepackJar)
 	jarjar 'com.googlecode.jarjar:jarjar:1.3'
 	jmustache 'com.samskivert:jmustache@jar'
-	optional 'javax.validation:validation-api'
 	optional 'commons-codec:commons-codec'
+	optional 'javax.validation:validation-api'
+	optional 'junit:junit'
 	testCompile 'org.mockito:mockito-core'
 	testCompile 'org.hamcrest:hamcrest-core'
 	testCompile 'org.hamcrest:hamcrest-library'

spring-restdocs-core/src/main/java/org/springframework/restdocs/JUnitRestDocumentation.java

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2014-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.restdocs;
+
+import org.junit.rules.TestRule;
+import org.junit.runner.Description;
+import org.junit.runners.model.Statement;
+
+/**
+ * A JUnit {@link TestRule} used to automatically manage the
+ * {@link RestDocumentationContext}.
+ *
+ * @author Andy Wilkinson
+ * @since 1.1.0
+ */
+public class JUnitRestDocumentation implements RestDocumentationContextProvider, TestRule {
+
+	private final ManualRestDocumentation delegate;
+
+	/**
+	 * Creates a new {@code JUnitRestDocumentation} instance that will generate snippets
+	 * to the given {@code outputDirectory}.
+	 *
+	 * @param outputDirectory the output directory
+	 */
+	public JUnitRestDocumentation(String outputDirectory) {
+		this.delegate = new ManualRestDocumentation(outputDirectory);
+	}
+
+	@Override
+	public Statement apply(final Statement base, final Description description) {
+		return new Statement() {
+
+			@Override
+			public void evaluate() throws Throwable {
+				Class<?> testClass = description.getTestClass();
+				String methodName = description.getMethodName();
+				JUnitRestDocumentation.this.delegate.beforeTest(testClass, methodName);
+				try {
+					base.evaluate();
+				}
+				finally {
+					JUnitRestDocumentation.this.delegate.afterTest();
+				}
+			}
+
+		};
+
+	}
+
+	@Override
+	public RestDocumentationContext beforeOperation() {
+		return this.delegate.beforeOperation();
+	}
+
+}

spring-restdocs-core/src/main/java/org/springframework/restdocs/ManualRestDocumentation.java

@@ -0,0 +1,82 @@
+/*
+ * 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.restdocs;
+
+import java.io.File;
+
+/**
+ * {@code ManualRestDocumentation} is used to manually manage the
+ * {@link RestDocumentationContext}. Primarly intended for use with TestNG, but suitable
+ * for use in any environment where manual management of the context is required.
+ * <p>
+ * Users of JUnit should use {@link JUnitRestDocumentation} and take advantage of its
+ * Rule-based support for automatic management of the context.
+ *
+ * @author Andy Wilkinson
+ * @since 1.1.0
+ */
+public final class ManualRestDocumentation implements RestDocumentationContextProvider {
+
+	private final File outputDirectory;
+
+	private RestDocumentationContext context;
+
+	/**
+	 * Creates a new {@code ManualRestDocumentation} instance that will generate snippets
+	 * to the given {@code outputDirectory}.
+	 *
+	 * @param outputDirectory the output directory
+	 */
+	public ManualRestDocumentation(String outputDirectory) {
+		this.outputDirectory = new File(outputDirectory);
+	}
+
+	/**
+	 * Notification that a test is about to begin. Creates a
+	 * {@link RestDocumentationContext} for the test on the given {@code testClass} with
+	 * the given {@code testMethodName}. Must be followed by a call to
+	 * {@link #afterTest()} once the test has completed.
+	 *
+	 * @param testClass the test class
+	 * @param testMethodName the name of the test method
+	 * @throws IllegalStateException if a context has already be created
+	 */
+	@SuppressWarnings("deprecation")
+	public void beforeTest(Class<?> testClass, String testMethodName) {
+		if (this.context != null) {
+			throw new IllegalStateException(
+					"Context already exists. Did you forget to call afterTest()?");
+		}
+		this.context = new RestDocumentationContext(testClass, testMethodName,
+				this.outputDirectory);
+	}
+
+	/**
+	 * Notification that a test has completed. Clears the {@link RestDocumentationContext}
+	 * that was previously established by a call to {@link #beforeTest(Class, String)}.
+	 */
+	public void afterTest() {
+		this.context = null;
+	}
+
+	@Override
+	public RestDocumentationContext beforeOperation() {
+		this.context.getAndIncrementStepCount();
+		return this.context;
+	}
+
+}

spring-restdocs-core/src/main/java/org/springframework/restdocs/RestDocumentation.java

@@ -16,8 +16,6 @@
 
 package org.springframework.restdocs;
 
-import java.io.File;
-
 import org.junit.rules.TestRule;
 import org.junit.runner.Description;
 import org.junit.runners.model.Statement;
@@ -27,13 +25,12 @@ import org.junit.runners.model.Statement;
  * JUnit tests.
  *
  * @author Andy Wilkinson
- *
+ * @deprecated Since 1.1 in favor of {@link JUnitRestDocumentation}
  */
-public class RestDocumentation implements TestRule {
+@Deprecated
+public class RestDocumentation implements TestRule, RestDocumentationContextProvider {
 
-	private final String outputDirectory;
-
-	private RestDocumentationContext context;
+	private final JUnitRestDocumentation delegate;
 
 	/**
 	 * Creates a new {@code RestDocumentation} instance that will generate snippets to the
@@ -42,40 +39,17 @@ public class RestDocumentation implements TestRule {
 	 * @param outputDirectory the output directory
 	 */
 	public RestDocumentation(String outputDirectory) {
-		this.outputDirectory = outputDirectory;
+		this.delegate = new JUnitRestDocumentation(outputDirectory);
 	}
 
 	@Override
 	public Statement apply(final Statement base, final Description description) {
-		return new Statement() {
-
-			@Override
-			public void evaluate() throws Throwable {
-				Class<?> testClass = description.getTestClass();
-				String methodName = description.getMethodName();
-				RestDocumentation.this.context = new RestDocumentationContext(testClass,
-						methodName, new File(RestDocumentation.this.outputDirectory));
-				try {
-					base.evaluate();
-				}
-				finally {
-					RestDocumentation.this.context = null;
-				}
-			}
-
-		};
-
+		return this.delegate.apply(base, description);
 	}
 
-	/**
-	 * Notification that a RESTful operation that should be documented is about to be
-	 * performed. Returns a {@link RestDocumentationContext} for the operation.
-	 *
-	 * @return the context for the operation
-	 */
+	@Override
 	public RestDocumentationContext beforeOperation() {
-		this.context.getAndIncrementStepCount();
-		return this.context;
+		return this.delegate.beforeOperation();
 	}
 
 }

spring-restdocs-core/src/main/java/org/springframework/restdocs/RestDocumentationContext.java

@@ -43,7 +43,9 @@ public final class RestDocumentationContext {
 	 * @param testClass the class whose test is being executed
 	 * @param testMethodName the name of the test method that is being executed
 	 * @param outputDirectory the directory to which documentation should be written.
+	 * @deprecated Since 1.1 in favor of {@link ManualRestDocumentation}.
 	 */
+	@Deprecated
 	public RestDocumentationContext(Class<?> testClass, String testMethodName,
 			File outputDirectory) {
 		this.testClass = testClass;

spring-restdocs-core/src/main/java/org/springframework/restdocs/RestDocumentationContextProvider.java

@@ -0,0 +1,36 @@
+/*
+ * 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.restdocs;
+
+/**
+ * A {@code RestDocumentationContextProvider} is used to provide access to the
+ * {@link RestDocumentationContext}.
+ *
+ * @author Andy Wilkinson
+ * @since 1.1.0
+ */
+public interface RestDocumentationContextProvider {
+
+	/**
+	 * Returns a {@link RestDocumentationContext} for the operation that is about to be
+	 * performed.
+	 *
+	 * @return the context for the operation
+	 */
+	RestDocumentationContext beforeOperation();
+
+}

spring-restdocs-mockmvc/build.gradle

@@ -3,6 +3,7 @@ description = 'Spring REST Docs MockMvc'
 dependencies {
 	compile 'org.springframework:spring-test'
 	compile project(':spring-restdocs-core')
+	optional 'junit:junit'
 
 	testCompile 'org.mockito:mockito-core'
 	testCompile 'org.hamcrest:hamcrest-library'

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

spring-restdocs-restassured/src/main/java/org/springframework/restdocs/restassured/RestAssuredRestDocumentation.java

@@ -16,7 +16,7 @@
 
 package org.springframework.restdocs.restassured;
 
-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;
@@ -104,14 +104,14 @@ public abstract class RestAssuredRestDocumentation {
 
 	/**
 	 * Provides access to a {@link RestAssuredRestDocumentationConfigurer} that can be
-	 * used to configure Spring REST Docs using the given {@code restDocumentation}.
+	 * used to configure Spring REST Docs using the given {@code contextProvider}.
 	 *
-	 * @param restDocumentation the REST documentation
+	 * @param contextProvider the context provider
 	 * @return the configurer
 	 */
 	public static RestAssuredRestDocumentationConfigurer documentationConfiguration(
-			RestDocumentation restDocumentation) {
-		return new RestAssuredRestDocumentationConfigurer(restDocumentation);
+			RestDocumentationContextProvider contextProvider) {
+		return new RestAssuredRestDocumentationConfigurer(contextProvider);
 	}
 
 }

spring-restdocs-restassured/src/main/java/org/springframework/restdocs/restassured/RestAssuredRestDocumentationConfigurer.java

@@ -19,8 +19,8 @@ package org.springframework.restdocs.restassured;
 import java.util.HashMap;
 import java.util.Map;
 
-import org.springframework.restdocs.RestDocumentation;
 import org.springframework.restdocs.RestDocumentationContext;
+import org.springframework.restdocs.RestDocumentationContextProvider;
 import org.springframework.restdocs.config.RestDocumentationConfigurer;
 
 import com.jayway.restassured.filter.Filter;
@@ -42,10 +42,11 @@ public final class RestAssuredRestDocumentationConfigurer
 	private final RestAssuredSnippetConfigurer snippetConfigurer = new RestAssuredSnippetConfigurer(
 			this);
 
-	private final RestDocumentation restDocumentation;
+	private final RestDocumentationContextProvider contextProvider;
 
-	RestAssuredRestDocumentationConfigurer(RestDocumentation restDocumentation) {
-		this.restDocumentation = restDocumentation;
+	RestAssuredRestDocumentationConfigurer(
+			RestDocumentationContextProvider contextProvider) {
+		this.contextProvider = contextProvider;
 	}
 
 	@Override
@@ -56,7 +57,7 @@ public final class RestAssuredRestDocumentationConfigurer
 	@Override
 	public Response filter(FilterableRequestSpecification requestSpec,
 			FilterableResponseSpecification responseSpec, FilterContext filterContext) {
-		RestDocumentationContext context = this.restDocumentation.beforeOperation();
+		RestDocumentationContext context = this.contextProvider.beforeOperation();
 		filterContext.setValue(RestDocumentationContext.class.getName(), context);
 		Map<String, Object> configuration = new HashMap<>();
 		filterContext.setValue(RestDocumentationFilter.CONTEXT_KEY_CONFIGURATION,

spring-restdocs-restassured/src/test/java/org/springframework/restdocs/restassured/RestAssuredRestDocumentationConfigurerTests.java

@@ -22,7 +22,7 @@ import java.util.Map;
 import org.junit.Rule;
 import org.junit.Test;
 import org.mockito.ArgumentCaptor;
-import org.springframework.restdocs.RestDocumentation;
+import org.springframework.restdocs.JUnitRestDocumentation;
 import org.springframework.restdocs.generate.RestDocumentationGenerator;
 import org.springframework.restdocs.snippet.WriterResolver;
 import org.springframework.restdocs.templates.TemplateEngine;
@@ -48,7 +48,7 @@ import static org.mockito.Mockito.verify;
 public class RestAssuredRestDocumentationConfigurerTests {
 
 	@Rule
-	public final RestDocumentation restDocumentation = new RestDocumentation("build");
+	public final JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("build");
 
 	private final FilterableRequestSpecification requestSpec = mock(FilterableRequestSpecification.class);
 

spring-restdocs-restassured/src/test/java/org/springframework/restdocs/restassured/RestAssuredRestDocumentationIntegrationTests.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.restassured.RestAssuredRestDocumentationIntegrationTests.TestApplication;
 import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
@@ -88,7 +88,7 @@ import static org.springframework.restdocs.test.SnippetMatchers.snippet;
 public class RestAssuredRestDocumentationIntegrationTests {
 
 	@Rule
-	public RestDocumentation restDocumentation = new RestDocumentation(
+	public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(
 			"build/generated-snippets");
 
 	@Value("${local.server.port}")