Document JUnit 5 before JUnit 4

Closes gh-864

Author: wilkinsona

Diff for: docs/src/docs/asciidoc/getting-started.adoc

@@ -201,24 +201,33 @@ It then produces documentation snippets for the request and the resulting respon
 ==== Setting up Your Tests
 
 Exactly how you set up your tests depends on the test framework that you use.
-Spring REST Docs provides first-class support for JUnit 4 and JUnit 5.
+Spring REST Docs provides first-class support for JUnit 5 and JUnit 4.
+JUnit 5 is recommended.
 Other frameworks, such as TestNG, are also supported, although slightly more setup is required.
 
 
 
-[[getting-started-documentation-snippets-setup-junit]]
-===== Setting up Your JUnit 4 Tests
+[[getting-started-documentation-snippets-setup-junit-5]]
+===== Setting up Your JUnit 5 Tests
 
-When using JUnit 4, the first step in generating documentation snippets is to declare a `public` `JUnitRestDocumentation` field that is annotated as a JUnit `@Rule`.
+When using JUnit 5, the first step in generating documentation snippets is to apply the `RestDocumentationExtension` to your test class.
 The following example shows how to do so:
 
 [source,java,indent=0]
 ----
-@Rule
-public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
+@ExtendWith(RestDocumentationExtension.class)
+public class JUnit5ExampleTests {
 ----
 
-By default, the `JUnitRestDocumentation` rule is automatically configured with an output directory based on your project's build tool:
+When testing a typical Spring application, you should also apply the `SpringExtension`:
+
+[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"]
 |===
@@ -231,38 +240,42 @@ By default, the `JUnitRestDocumentation` rule is automatically configured with a
 | `build/generated-snippets`
 |===
 
-You can override the default by providing an output directory when you create the `JUnitRestDocumentation` instance.
+If you are using JUnit 5.1, you can override the default by registering the extension as a field in your test class and providing an output directory when creating it.
 The following example shows how to do so:
 
 [source,java,indent=0]
 ----
-@Rule
-public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("custom");
+public class JUnit5ExampleTests {
+
+	@RegisterExtension
+	final RestDocumentationExtension restDocumentation = new RestDocumentationExtension ("custom");
+
+}
 ----
 
-Next, you must provide an `@Before` method to configure MockMvc or WebTestClient, or REST Assured.
-The following examples show how to do so:
+Next, you must provide a `@BeforeEach` method to configure MockMvc or WebTestClient, or REST Assured.
+The following listings show how to do so:
 
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
-include::{examples-dir}/com/example/mockmvc/ExampleApplicationTests.java[tags=setup]
+include::{examples-dir}/com/example/mockmvc/ExampleApplicationJUnit5Tests.java[tags=setup]
 ----
 <1> The `MockMvc` instance is configured by using a `MockMvcRestDocumentationConfigurer`.
 You can obtain an instance of this class from the static `documentationConfiguration()` method on `org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`.
 
 [source,java,indent=0,role="secondary"]
 .WebTestClient
 ----
-include::{examples-dir}/com/example/webtestclient/ExampleApplicationTests.java[tags=setup]
+include::{examples-dir}/com/example/webtestclient/ExampleApplicationJUnit5Tests.java[tags=setup]
 ----
-<1> The `WebTestClient` instance is configured by adding a `WebTestclientRestDocumentationConfigurer` as an `ExchangeFilterFunction`.
+<1> The `WebTestClient` instance is configured by adding a `WebTestClientRestDocumentationConfigurer` as an `ExchangeFilterFunction`.
 You can obtain an instance of this class from the static `documentationConfiguration()` method on `org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation`.
 
 [source,java,indent=0,role="secondary"]
 .REST Assured
 ----
-include::{examples-dir}/com/example/restassured/ExampleApplicationTests.java[tags=setup]
+include::{examples-dir}/com/example/restassured/ExampleApplicationJUnit5Tests.java[tags=setup]
 ----
 <1> REST Assured is configured by adding a `RestAssuredRestDocumentationConfigurer` as a `Filter`.
 You can obtain an instance of this class from the static `documentationConfiguration()` method on `RestAssuredRestDocumentation` in the `org.springframework.restdocs.restassured` package.
@@ -272,27 +285,19 @@ See the <<configuration, configuration section>> for more information.
 
 
 
-[[getting-started-documentation-snippets-setup-junit-5]]
-===== Setting up Your JUnit 5 Tests
+[[getting-started-documentation-snippets-setup-junit]]
+===== Setting up Your JUnit 4 Tests
 
-When using JUnit 5, the first step in generating documentation snippets is to apply the `RestDocumentationExtension` to your test class.
+When using JUnit 4, the first step in generating documentation snippets is to declare a `public` `JUnitRestDocumentation` field that is annotated as a JUnit `@Rule`.
 The following example shows how to do so:
 
 [source,java,indent=0]
 ----
-@ExtendWith(RestDocumentationExtension.class)
-public class JUnit5ExampleTests {
-----
-
-When testing a typical Spring application, you should also apply the `SpringExtension`:
-
-[source,java,indent=0]
-----
-@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
-public class JUnit5ExampleTests {
+@Rule
+public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
 ----
 
-The `RestDocumentationExtension` is automatically configured with an output directory based on your project's build tool:
+By default, the `JUnitRestDocumentation` rule is automatically configured with an output directory based on your project's build tool:
 
 [cols="2,5"]
 |===
@@ -305,42 +310,38 @@ The `RestDocumentationExtension` is automatically configured with an output dire
 | `build/generated-snippets`
 |===
 
-If you are using JUnit 5.1, you can override the default by registering the extension as a field in your test class and providing an output directory when creating it.
+You can override the default by providing an output directory when you create the `JUnitRestDocumentation` instance.
 The following example shows how to do so:
 
 [source,java,indent=0]
 ----
-public class JUnit5ExampleTests {
-
-	@RegisterExtension
-	final RestDocumentationExtension restDocumentation = new RestDocumentationExtension ("custom");
-
-}
+@Rule
+public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("custom");
 ----
 
-Next, you must provide a `@BeforeEach` method to configure MockMvc or WebTestClient, or REST Assured.
-The following listings show how to do so:
+Next, you must provide an `@Before` method to configure MockMvc or WebTestClient, or REST Assured.
+The following examples show how to do so:
 
 [source,java,indent=0,role="primary"]
 .MockMvc
 ----
-include::{examples-dir}/com/example/mockmvc/ExampleApplicationJUnit5Tests.java[tags=setup]
+include::{examples-dir}/com/example/mockmvc/ExampleApplicationTests.java[tags=setup]
 ----
 <1> The `MockMvc` instance is configured by using a `MockMvcRestDocumentationConfigurer`.
 You can obtain an instance of this class from the static `documentationConfiguration()` method on `org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`.
 
 [source,java,indent=0,role="secondary"]
 .WebTestClient
 ----
-include::{examples-dir}/com/example/webtestclient/ExampleApplicationJUnit5Tests.java[tags=setup]
+include::{examples-dir}/com/example/webtestclient/ExampleApplicationTests.java[tags=setup]
 ----
-<1> The `WebTestClient` instance is configured by adding a `WebTestClientRestDocumentationConfigurer` as an `ExchangeFilterFunction`.
+<1> The `WebTestClient` instance is configured by adding a `WebTestclientRestDocumentationConfigurer` as an `ExchangeFilterFunction`.
 You can obtain an instance of this class from the static `documentationConfiguration()` method on `org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation`.
 
 [source,java,indent=0,role="secondary"]
 .REST Assured
 ----
-include::{examples-dir}/com/example/restassured/ExampleApplicationJUnit5Tests.java[tags=setup]
+include::{examples-dir}/com/example/restassured/ExampleApplicationTests.java[tags=setup]
 ----
 <1> REST Assured is configured by adding a `RestAssuredRestDocumentationConfigurer` as a `Filter`.
 You can obtain an instance of this class from the static `documentationConfiguration()` method on `RestAssuredRestDocumentation` in the `org.springframework.restdocs.restassured` package.