Skip to content

Commit 352e3ca

Browse files
wilkinsonawilkinsona
committed
Polish "Add auto-configuration for REST Docs with REST Assured"
Closes gh-9643
1 parent 98b2267 commit 352e3ca

File tree

10 files changed

+175
-36
lines changed

10 files changed

+175
-36
lines changed

‎spring-boot-docs/pom.xml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,14 @@
5555
<groupId>org.springframework.boot</groupId>
5656
<artifactId>spring-boot-test-autoconfigure</artifactId>
5757
</dependency>
58+
<dependency>
59+
<groupId>io.rest-assured</groupId>
60+
<artifactId>rest-assured</artifactId>
61+
</dependency>
62+
<dependency>
63+
<groupId>org.springframework.restdocs</groupId>
64+
<artifactId>spring-restdocs-restassured</artifactId>
65+
</dependency>
5866
<!-- Optional deps required when generating Javadoc with Java 8 -->
5967
<dependency>
6068
<groupId>ch.qos.logback</groupId>

‎spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc

Lines changed: 40 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6279,8 +6279,20 @@ A list of the auto-configuration that is enabled by `@RestClientTest` can be
62796279
[[boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs]]
62806280
==== Auto-configured Spring REST Docs tests
62816281
The `@AutoConfigureRestDocs` annotation can be used if you want to use Spring REST Docs
6282-
in your tests. It will automatically configure `MockMvc` to use Spring REST Docs and
6283-
remove the need for Spring REST Docs' JUnit rule.
6282+
in your tests with Mock MVC or REST Assured. It removes the need for Spring REST Docs'
6283+
JUnit rule.
6284+
6285+
`@AutoConfigureRestDocs` can be used to override the default output directory
6286+
(`target/generated-snippets` if you are using Maven or `build/generated-snippets` if you
6287+
are using Gradle). It can also be used to configure the host, scheme, and port that will
6288+
appear in any documented URIs.
6289+
6290+
[[boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs-mock-mvc]]
6291+
===== Auto-configured Spring REST Docs tests with Mock MVC
6292+
6293+
`@AutoConfigureRestDocs` customizes the `MockMvc` bean to use Spring REST Docs, Inject it
6294+
using `@Autowired` and use it in your tests as you normally would when using Mock MVC and
6295+
Spring REST Docs:
62846296

62856297
[source,java,indent=0]
62866298
----
@@ -6315,11 +6327,9 @@ remove the need for Spring REST Docs' JUnit rule.
63156327
}
63166328
----
63176329

6318-
`@AutoConfigureRestDocs` can be used to override the default output directory
6319-
(`target/generated-snippets` if you are using Maven or `build/generated-snippets` if you
6320-
are using Gradle). It can also be used to configure the host, scheme, and port that will
6321-
appear in any documented URIs. If you require more control over Spring REST Docs'
6322-
configuration a `RestDocsMockMvcConfigurationCustomizer` bean can be used:
6330+
If you require more control over Spring REST Docs' configuration than offered by the
6331+
attributes of `@AutoConfigureRestDocs`, a `RestDocsMockMvcConfigurationCustomizer` bean
6332+
can be used:
63236333

63246334
[source,java,indent=0]
63256335
----
@@ -6355,6 +6365,29 @@ automatically generate the default snippets:
63556365

63566366

63576367

6368+
[[boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs-rest-assured]]
6369+
===== Auto-configured Spring REST Docs tests with REST Assured
6370+
6371+
`@AutoConfigureRestDocs` makes a `RequestSpecification` bean, preconfigured to use Spring REST
6372+
Docs, available to your tests. Inject it using `@Autowired` and use it in your tests as you
6373+
normally would when using REST Assured and Spring REST Docs:
6374+
6375+
[source,java,indent=0]
6376+
----
6377+
include::{code-examples}/test/autoconfigure/restdocs/restassured/UserDocumentationTests.java[tag=source]
6378+
----
6379+
6380+
If you require more control over Spring REST Docs' configuration than offered by the
6381+
attributes of `@AutoConfigureRestDocs`, a `RestDocsRestAssuredConfigurationCustomizer`
6382+
bean can be used:
6383+
6384+
[source,java,indent=0]
6385+
----
6386+
include::{code-examples}/test/autoconfigure/restdocs/restassured/AdvancedConfigurationExample.java[tag=configuration]
6387+
----
6388+
6389+
6390+
63586391
[[boot-features-testing-spring-boot-applications-with-spock]]
63596392
==== Using Spock to test Spring Boot applications
63606393
If you wish to use Spock to test a Spring Boot application you should add a dependency

‎spring-boot-docs/src/main/java/org/springframework/boot/test/autoconfigure/restdocs/restassured/AdvancedConfigurationExample.java

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
/*
2+
* Copyright 2012-2017 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package org.springframework.boot.test.autoconfigure.restdocs.restassured;
18+
19+
import org.springframework.boot.test.autoconfigure.restdocs.RestDocsRestAssuredConfigurationCustomizer;
20+
import org.springframework.boot.test.context.TestConfiguration;
21+
import org.springframework.restdocs.restassured3.RestAssuredRestDocumentationConfigurer;
22+
import org.springframework.restdocs.templates.TemplateFormats;
23+
24+
public class AdvancedConfigurationExample {
25+
26+
// tag::configuration[]
27+
@TestConfiguration
28+
public static class CustomizationConfiguration
29+
implements RestDocsRestAssuredConfigurationCustomizer {
30+
31+
@Override
32+
public void customize(RestAssuredRestDocumentationConfigurer configurer) {
33+
configurer.snippets().withTemplateFormat(TemplateFormats.markdown());
34+
}
35+
36+
}
37+
// end::configuration[]
38+
39+
}

‎spring-boot-docs/src/main/java/org/springframework/boot/test/autoconfigure/restdocs/restassured/UserDocumentationTests.java

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
/*
2+
* Copyright 2012-2017 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package org.springframework.boot.test.autoconfigure.restdocs.restassured;
18+
19+
// tag::source[]
20+
import io.restassured.specification.RequestSpecification;
21+
import org.junit.Test;
22+
import org.junit.runner.RunWith;
23+
24+
import org.springframework.beans.factory.annotation.Autowired;
25+
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
26+
import org.springframework.boot.test.context.SpringBootTest;
27+
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
28+
import org.springframework.boot.web.server.LocalServerPort;
29+
import org.springframework.test.context.junit4.SpringRunner;
30+
31+
import static io.restassured.RestAssured.given;
32+
import static org.hamcrest.CoreMatchers.is;
33+
import static org.springframework.restdocs.restassured3.RestAssuredRestDocumentation.document;
34+
35+
@RunWith(SpringRunner.class)
36+
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
37+
@AutoConfigureRestDocs
38+
public class UserDocumentationTests {
39+
40+
@LocalServerPort
41+
private int port;
42+
43+
@Autowired
44+
private RequestSpecification documentationSpec;
45+
46+
@Test
47+
public void listUsers() throws Exception {
48+
given(this.documentationSpec).filter(document("list-users")).when()
49+
.port(this.port).get("/").then().assertThat().statusCode(is(200));
50+
}
51+
52+
}
53+
// end::source[]

‎spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/restdocs/RestDocsAutoConfiguration.java

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -45,11 +45,12 @@
4545
*/
4646
@Configuration
4747
@EnableConfigurationProperties
48+
@ConditionalOnWebApplication
4849
public class RestDocsAutoConfiguration {
4950

5051
@Configuration
51-
@ConditionalOnWebApplication(type = Type.SERVLET)
5252
@ConditionalOnClass(MockMvcRestDocumentation.class)
53+
@ConditionalOnWebApplication(type = Type.SERVLET)
5354
static class RestDocsMockMvcAutoConfiguration {
5455

5556
@Bean
@@ -79,7 +80,8 @@ public RestDocsMockMvcBuilderCustomizer restDocumentationConfigurer(
7980
}
8081

8182
@Configuration
82-
@ConditionalOnClass({ RequestSpecification.class, RestAssuredRestDocumentation.class })
83+
@ConditionalOnClass({ RequestSpecification.class,
84+
RestAssuredRestDocumentation.class })
8385
static class RestDocsRestAssuredAutoConfiguration {
8486

8587
@Bean
@@ -89,7 +91,8 @@ public RequestSpecification restDocsRestAssuredConfigurer(
8991
RestDocumentationContextProvider contextProvider) {
9092
RestAssuredRestDocumentationConfigurer configurer = RestAssuredRestDocumentation
9193
.documentationConfiguration(contextProvider);
92-
RestDocsRestAssuredConfigurationCustomizer configurationCustomizer = configurationCustomizerProvider.getIfAvailable();
94+
RestDocsRestAssuredConfigurationCustomizer configurationCustomizer = configurationCustomizerProvider
95+
.getIfAvailable();
9396
if (configurationCustomizer != null) {
9497
configurationCustomizer.customize(configurer);
9598
}
@@ -105,5 +108,4 @@ public RestDocsRestAssuredBuilderCustomizer restAssuredBuilderCustomizer(
105108

106109
}
107110

108-
109111
}

‎spring-boot-test-autoconfigure/src/main/java/org/springframework/boot/test/autoconfigure/restdocs/RestDocsRestAssuredBuilderCustomizer.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
import org.springframework.util.StringUtils;
2323

2424
/**
25-
* A customizer that configures Spring REST Docs with RestAssured.
25+
* A customizer that configures Spring REST Docs with REST Assured.
2626
*
2727
* @author Eddú Meléndez
2828
*/

‎spring-boot-test-autoconfigure/src/test/java/org/springframework/boot/test/autoconfigure/restdocs/RestDocsAutoConfigurationAdvancedConfigurationIntegrationTests.java renamed to ‎spring-boot-test-autoconfigure/src/test/java/org/springframework/boot/test/autoconfigure/restdocs/MockMvcRestDocsAutoConfigurationAdvancedConfigurationIntegrationTests.java

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,14 +41,15 @@
4141
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
4242

4343
/**
44-
* Tests for {@link AutoConfigureRestDocs}.
44+
* Integration tests for advanced configuration of {@link AutoConfigureRestDocs} with Mock
45+
* MVC.
4546
*
4647
* @author Andy Wilkinson
4748
*/
4849
@RunWith(SpringRunner.class)
4950
@WebMvcTest(controllers = RestDocsTestController.class, secure = false)
5051
@AutoConfigureRestDocs
51-
public class RestDocsAutoConfigurationAdvancedConfigurationIntegrationTests {
52+
public class MockMvcRestDocsAutoConfigurationAdvancedConfigurationIntegrationTests {
5253

5354
@Before
5455
public void deleteSnippets() {

‎spring-boot-test-autoconfigure/src/test/java/org/springframework/boot/test/autoconfigure/restdocs/RestDocsAutoConfigurationIntegrationTests.java renamed to ‎spring-boot-test-autoconfigure/src/test/java/org/springframework/boot/test/autoconfigure/restdocs/MockMvcRestDocsAutoConfigurationIntegrationTests.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,14 +34,14 @@
3434
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
3535

3636
/**
37-
* Tests for {@link RestDocsAutoConfiguration}.
37+
* Integration tests for {@link RestDocsAutoConfiguration} with Mock MVC.
3838
*
3939
* @author Andy Wilkinson
4040
*/
4141
@RunWith(SpringRunner.class)
4242
@WebMvcTest
4343
@AutoConfigureRestDocs(uriScheme = "https", uriHost = "api.example.com", uriPort = 443)
44-
public class RestDocsAutoConfigurationIntegrationTests {
44+
public class MockMvcRestDocsAutoConfigurationIntegrationTests {
4545

4646
@Before
4747
public void deleteSnippets() {

‎spring-boot-test-autoconfigure/src/test/java/org/springframework/boot/test/autoconfigure/restdocs/RestAssuredAutoConfigurationAdvancedConfigurationIntegrationTests.java renamed to ‎spring-boot-test-autoconfigure/src/test/java/org/springframework/boot/test/autoconfigure/restdocs/RestAssuredRestDocsAutoConfigurationAdvancedConfigurationIntegrationTests.java

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -42,14 +42,15 @@
4242
import static org.springframework.restdocs.restassured3.operation.preprocess.RestAssuredPreprocessors.modifyUris;
4343

4444
/**
45-
* Tests for {@link AutoConfigureRestDocs}.
45+
* Integration tests for advanced configuration of {@link AutoConfigureRestDocs} with REST
46+
* Assured.
4647
*
4748
* @author Eddú Meléndez
4849
*/
4950
@RunWith(SpringRunner.class)
5051
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
5152
@AutoConfigureRestDocs
52-
public class RestAssuredAutoConfigurationAdvancedConfigurationIntegrationTests {
53+
public class RestAssuredRestDocsAutoConfigurationAdvancedConfigurationIntegrationTests {
5354

5455
@LocalServerPort
5556
private int port;
@@ -65,15 +66,16 @@ public void deleteSnippets() {
6566
@Test
6667
public void snippetGeneration() throws Exception {
6768
given(this.documentationSpec)
68-
.filter(document("default-snippets", preprocessRequest(modifyUris()
69-
.scheme("https").host("api.example.com").removePort()))).when()
70-
.port(this.port).get("/").then().assertThat().statusCode(is(200));
69+
.filter(document("default-snippets",
70+
preprocessRequest(modifyUris().scheme("https")
71+
.host("api.example.com").removePort())))
72+
.when().port(this.port).get("/").then().assertThat().statusCode(is(200));
7173
File defaultSnippetsDir = new File("target/generated-snippets/default-snippets");
7274
assertThat(defaultSnippetsDir).exists();
73-
assertThat(new File(defaultSnippetsDir, "curl-request.md")).has(
74-
contentContaining("'https://api.example.com/'"));
75-
assertThat(new File(defaultSnippetsDir, "http-request.md")).has(
76-
contentContaining("api.example.com"));
75+
assertThat(new File(defaultSnippetsDir, "curl-request.md"))
76+
.has(contentContaining("'https://api.example.com/'"));
77+
assertThat(new File(defaultSnippetsDir, "http-request.md"))
78+
.has(contentContaining("api.example.com"));
7779
assertThat(new File(defaultSnippetsDir, "http-response.md")).isFile();
7880
}
7981

@@ -82,8 +84,8 @@ private Condition<File> contentContaining(String toContain) {
8284
}
8385

8486
@TestConfiguration
85-
public static class CustomizationConfiguration implements
86-
RestDocsRestAssuredConfigurationCustomizer {
87+
public static class CustomizationConfiguration
88+
implements RestDocsRestAssuredConfigurationCustomizer {
8789

8890
@Override
8991
public void customize(RestAssuredRestDocumentationConfigurer configurer) {

‎spring-boot-test-autoconfigure/src/test/java/org/springframework/boot/test/autoconfigure/restdocs/RestAssuredAutoConfigurationIntegrationTests.java renamed to ‎spring-boot-test-autoconfigure/src/test/java/org/springframework/boot/test/autoconfigure/restdocs/RestAssuredRestDocsAutoConfigurationIntegrationTests.java

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -39,14 +39,14 @@
3939
import static org.springframework.restdocs.restassured3.operation.preprocess.RestAssuredPreprocessors.modifyUris;
4040

4141
/**
42-
* Tests for {@link RestDocsAutoConfiguration}
42+
* Integration tests for {@link RestDocsAutoConfiguration} with REST Assured.
4343
*
4444
* @author Eddú Meléndez
4545
*/
4646
@RunWith(SpringRunner.class)
4747
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
4848
@AutoConfigureRestDocs
49-
public class RestAssuredAutoConfigurationIntegrationTests {
49+
public class RestAssuredRestDocsAutoConfigurationIntegrationTests {
5050

5151
@LocalServerPort
5252
private int port;
@@ -62,15 +62,16 @@ public void deleteSnippets() {
6262
@Test
6363
public void defaultSnippetsAreWritten() throws Exception {
6464
given(this.documentationSpec)
65-
.filter(document("default-snippets", preprocessRequest(modifyUris()
66-
.scheme("https").host("api.example.com").removePort()))).when()
67-
.port(this.port).get("/").then().assertThat().statusCode(is(200));
65+
.filter(document("default-snippets",
66+
preprocessRequest(modifyUris().scheme("https")
67+
.host("api.example.com").removePort())))
68+
.when().port(this.port).get("/").then().assertThat().statusCode(is(200));
6869
File defaultSnippetsDir = new File("target/generated-snippets/default-snippets");
6970
assertThat(defaultSnippetsDir).exists();
70-
assertThat(new File(defaultSnippetsDir, "curl-request.adoc")).has(
71-
contentContaining("'https://api.example.com/'"));
72-
assertThat(new File(defaultSnippetsDir, "http-request.adoc")).has(
73-
contentContaining("api.example.com"));
71+
assertThat(new File(defaultSnippetsDir, "curl-request.adoc"))
72+
.has(contentContaining("'https://api.example.com/'"));
73+
assertThat(new File(defaultSnippetsDir, "http-request.adoc"))
74+
.has(contentContaining("api.example.com"));
7475
assertThat(new File(defaultSnippetsDir, "http-response.adoc")).isFile();
7576
}
7677

0 commit comments

Comments
 (0)