Add support for JUnit 5

This commit adds support for JUnit 5 and its Jupiter programming
model. A new Jupiter Extension implementation,
RestDocumentationExtension, is provided. This extension can be applied
to a test class to allow it to use Spring REST Docs to document a
RESTful API.

Closes gh-296

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

@@ -60,6 +60,10 @@ If you want to jump straight in, a number of sample applications are available:
 | Gradle
 | Demonstrates the use of Spring REST Docs with http://testng.org[TestNG].
 
+| {samples}/junit5[JUnit 5]
+| Gradle
+| Demonstrates the use of Spring REST Docs with http://junit.org/junit5/[JUnit 5].
+
 |===
 
 [[getting-started-requirements]]
@@ -257,13 +261,13 @@ response.
 ==== Setting up your tests
 
 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.
+Spring REST Docs provides first-class support for JUnit 4 and JUnit 5. 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
+===== Setting up your JUnit 4 tests
 
-When using JUnit, the first step in generating documentation snippets is to declare a
+When using JUnit 4, the first step in generating documentation snippets is to declare a
 `public` `JUnitRestDocumentation` field that's annotated as a JUnit `@Rule`.
 
 
@@ -325,6 +329,69 @@ configuration. Refer to the <<configuration, configuration section>> for more in
 
 
 
+[[getting-started-documentation-snippets-setup-junit-5]]
+===== Setting up your JUnit 5 tests
+
+When using JUnit 5, the first step in generating documentation snippets is to apply
+the `RestDocumentationExtension` to your test class:
+
+[source,java,indent=0]
+----
+@ExtendWith(RestDocumentationExtension.class)
+public class JUnit5ExampleTests {
+----
+
+For testing a typical Spring application the `SpringExtension` should also be applied:
+
+[source,java,indent=0]
+----
+@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
+public class JUnit5ExampleTests {
+----
+
+The `RestDocumentationExtension` is automatically configured with an output directory
+based on your project's build tool:
+
+[cols="2,5"]
+|===
+| Build tool | Output directory
+
+| Maven
+| `target/generated-snippets`
+
+| Gradle
+| `build/generated-snippets`
+
+|===
+
+
+
+Next, provide an `@BeforeEach` method to configure MockMvc or REST Assured:
+
+[source,java,indent=0,role="primary"]
+.MockMvc
+----
+include::{examples-dir}/com/example/mockmvc/ExampleApplicationJUnit5Tests.java[tags=setup]
+----
+<1> The `MockMvc` instance is configured using a `MockMvcRestDocumentationConfigurer`. An
+instance of this class can be obtained from the static `documentationConfiguration()`
+method on `org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`.
+
+[source,java,indent=0,role="secondary"]
+.REST Assured
+----
+include::{examples-dir}/com/example/restassured/ExampleApplicationJUnit5Tests.java[tags=setup]
+----
+<1> REST Assured is configured by adding a `RestAssuredRestDocumentationConfigurer` as a
+`Filter`. An instance of this class can be obtained from the static
+`documentationConfiguration()` method on `RestAssuredRestDocumentation` in the
+`org.springframework.restdocs.restassured3` package.
+
+The configurer applies sensible defaults and also provides an API for customizing the
+configuration. Refer to the <<configuration, configuration section>> for more information.
+
+
+
 ===== Setting up your tests without JUnit
 [[getting-started-documentation-snippets-setup-manual]]
 

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

@@ -0,0 +1,46 @@
+/*
+ * 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 org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.extension.ExtendWith;
+
+import org.springframework.restdocs.RestDocumentationContextProvider;
+import org.springframework.restdocs.RestDocumentationExtension;
+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;
+
+@ExtendWith(RestDocumentationExtension.class)
+public class ExampleApplicationJUnit5Tests {
+
+	@SuppressWarnings("unused")
+	// tag::setup[]
+	private MockMvc mockMvc;
+
+	@BeforeEach
+	public void setUp(WebApplicationContext webApplicationContext,
+			RestDocumentationContextProvider restDocumentation) {
+		this.mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext)
+				.apply(documentationConfiguration(restDocumentation)) // <1>
+				.build();
+	}
+	// end::setup[]
+
+}

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

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2014-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 com.example.restassured;
+
+import io.restassured.builder.RequestSpecBuilder;
+import io.restassured.specification.RequestSpecification;
+import org.junit.Before;
+import org.junit.jupiter.api.extension.ExtendWith;
+
+import org.springframework.restdocs.RestDocumentationContextProvider;
+import org.springframework.restdocs.RestDocumentationExtension;
+
+import static org.springframework.restdocs.restassured3.RestAssuredRestDocumentation.documentationConfiguration;
+
+@ExtendWith(RestDocumentationExtension.class)
+public class ExampleApplicationJUnit5Tests {
+
+	@SuppressWarnings("unused")
+	// tag::setup[]
+	private RequestSpecification spec;
+
+	@Before
+	public void setUp(RestDocumentationContextProvider restDocumentation) {
+		this.spec = new RequestSpecBuilder()
+				.addFilter(documentationConfiguration(restDocumentation)) // <1>
+				.build();
+	}
+	// end::setup[]
+}