Configuration

This section covers how to configure Spring REST Docs.spring-doc.cn

Documented URIs

This section covers configuring documented URIs.spring-doc.cn

MockMvc URI Customization

When using MockMvc, the default configuration for URIs documented by Spring REST Docs is as follows:spring-doc.cn

Setting Default

Schemespring-doc.cn

httpspring-doc.cn

Hostspring-doc.cn

localhostspring-doc.cn

Portspring-doc.cn

8080spring-doc.cn

This configuration is applied by MockMvcRestDocumentationConfigurer. You can use its API to change one or more of the defaults to suit your needs. The following example shows how to do so:spring-doc.cn

this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
	.apply(documentationConfiguration(this.restDocumentation).uris()
		.withScheme("https")
		.withHost("example.com")
		.withPort(443))
	.build();
If the port is set to the default for the configured scheme (port 80 for HTTP or port 443 for HTTPS), it is omitted from any URIs in the generated snippets.
To configure a request’s context path, use the contextPath method on MockHttpServletRequestBuilder.

REST Assured URI Customization

REST Assured tests a service by making actual HTTP requests. As a result, URIs must be customized once the operation on the service has been performed but before it is documented. A REST-Assured-specific preprocessor is provided for this purpose.spring-doc.cn

WebTestClient URI Customization

When using WebTestClient, the default base for URIs documented by Spring REST Docs is http://localhost:8080. You can customize this base by using the baseUrl(String) method on WebTestClient.Builder. The following example shows how to do so:spring-doc.cn

@Before
public void setUp() {
	this.webTestClient = WebTestClient.bindToApplicationContext(this.context)
		.configureClient()
		.baseUrl("https://api.example.com") (1)
		.filter(documentationConfiguration(this.restDocumentation))
		.build();
}
1 Configure the base of documented URIs to be https://api.example.com.

Snippet Encoding

The default snippet encoding is UTF-8. You can change the default snippet encoding by using the RestDocumentationConfigurer API. For example, the following examples use ISO-8859-1:spring-doc.cn

MockMvc
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
	.apply(documentationConfiguration(this.restDocumentation).snippets().withEncoding("ISO-8859-1"))
	.build();
WebTestClient
this.webTestClient = WebTestClient.bindToApplicationContext(this.context).configureClient()
	.filter(documentationConfiguration(this.restDocumentation)
		.snippets().withEncoding("ISO-8859-1"))
	.build();
REST Assured
this.spec = new RequestSpecBuilder()
	.addFilter(documentationConfiguration(this.restDocumentation).snippets().withEncoding("ISO-8859-1"))
	.build();
When Spring REST Docs converts the content of a request or a response to a String, the charset specified in the Content-Type header is used if it is available. In its absence, the JVM’s default Charset is used. You can configure the JVM’s default Charset by using the file.encoding system property.

Snippet Template Format

The default snippet template format is Asciidoctor. Markdown is also supported out of the box. You can change the default format by using the RestDocumentationConfigurer API. The following examples show how to do so:spring-doc.cn

MockMvc
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
	.apply(documentationConfiguration(this.restDocumentation).snippets()
		.withTemplateFormat(TemplateFormats.markdown()))
	.build();
WebTestClient
this.webTestClient = WebTestClient.bindToApplicationContext(this.context).configureClient()
	.filter(documentationConfiguration(this.restDocumentation)
		.snippets().withTemplateFormat(TemplateFormats.markdown()))
	.build();
REST Assured
this.spec = new RequestSpecBuilder()
	.addFilter(documentationConfiguration(this.restDocumentation).snippets()
		.withTemplateFormat(TemplateFormats.markdown()))
	.build();

Default Snippets

Six snippets are produced by default:spring-doc.cn

You can change the default snippet configuration during setup by using the RestDocumentationConfigurer API. The following examples produce only the curl-request snippet by default:spring-doc.cn

MockMvc
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
	.apply(documentationConfiguration(this.restDocumentation).snippets().withDefaults(curlRequest()))
	.build();
WebTestClient
this.webTestClient = WebTestClient.bindToApplicationContext(this.context)
	.configureClient().filter(
		documentationConfiguration(this.restDocumentation)
			.snippets().withDefaults(curlRequest()))
	.build();
REST Assured
this.spec = new RequestSpecBuilder()
	.addFilter(documentationConfiguration(this.restDocumentation).snippets().withDefaults(curlRequest()))
	.build();

Default Operation Preprocessors

You can configure default request and response preprocessors during setup by using the RestDocumentationConfigurer API. The following examples remove the Foo headers from all requests and pretty print all responses:spring-doc.cn

MockMvc
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
	.apply(documentationConfiguration(this.restDocumentation).operationPreprocessors()
		.withRequestDefaults(modifyHeaders().remove("Foo")) (1)
		.withResponseDefaults(prettyPrint())) (2)
	.build();
1 Apply a request preprocessor that removes the header named Foo.
2 Apply a response preprocessor that pretty prints its content.
WebTestClient
this.webTestClient = WebTestClient.bindToApplicationContext(this.context)
	.configureClient()
	.filter(documentationConfiguration(this.restDocumentation)
		.operationPreprocessors()
			.withRequestDefaults(modifyHeaders().remove("Foo")) (1)
			.withResponseDefaults(prettyPrint())) (2)
	.build();
1 Apply a request preprocessor that removes the header named Foo.
2 Apply a response preprocessor that pretty prints its content.
REST Assured
this.spec = new RequestSpecBuilder()
	.addFilter(documentationConfiguration(this.restDocumentation).operationPreprocessors()
		.withRequestDefaults(modifyHeaders().remove("Foo")) (1)
		.withResponseDefaults(prettyPrint())) (2)
	.build();
1 Apply a request preprocessor that removes the header named Foo.
2 Apply a response preprocessor that pretty prints its content.