This version is still in development and is not considered stable yet. For the latest stable version, please use Spring REST Docs 4.0.0!

Customizing requests and responses

There may be situations where you do not want to document a request exactly as it was sent or a response exactly as it was received. Spring REST Docs provides a number of preprocessors that can be used to modify a request or response before it is documented.

Preprocessing is configured by calling document with an OperationRequestPreprocessor or an OperationResponsePreprocessor. You can obtain instances by using the static preprocessRequest and preprocessResponse methods on Preprocessors. The following examples show how to do so:

MockMvc
WebTestClient

import org.junit.jupiter.api.Test;

import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.modifyHeaders;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessRequest;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessResponse;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

class PerTestPreprocessing {

	// Fields

	private MockMvc mockMvc;


	@Test
	void test() throws Exception {
		this.mockMvc.perform(get("/"))
			.andExpect(status().isOk())
			.andDo(document("index", preprocessRequest(modifyHeaders().remove("Foo")), (1)
					preprocessResponse(prettyPrint()))); (2)
	}

}

1	Apply a request preprocessor that removes the header named `Foo`.
2	Apply a response preprocessor that pretty prints its content.

import org.junit.jupiter.api.Test;

import org.springframework.test.web.reactive.server.WebTestClient;

import static org.springframework.restdocs.operation.preprocess.Preprocessors.modifyHeaders;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessRequest;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessResponse;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;
import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document;

class PerTestPreprocessing {

	// Fields

	private WebTestClient webTestClient;


	@Test
	void test() {
		this.webTestClient.get()
			.uri("/")
			.exchange()
			.expectStatus()
			.isOk()
			.expectBody()
			.consumeWith(document("index", preprocessRequest(modifyHeaders().remove("Foo")), (1)
					preprocessResponse(prettyPrint()))); (2)
	}

}

1	Apply a request preprocessor that removes the header named `Foo`.
2	Apply a response preprocessor that pretty prints its content.

Alternatively, you may want to apply the same preprocessors to every test. You can do so by using the RestDocumentationConfigurer API in your @BeforeEach method to configure the preprocessors. For example, to remove the Foo header from all requests and pretty print all responses, you could do one of the following (depending on your testing environment):

MockMvc
WebTestClient

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.extension.ExtendWith;

import org.springframework.beans.factory.annotation.Autowired;
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;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.modifyHeaders;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;

@ExtendWith(RestDocumentationExtension.class)
public class EveryTestPreprocessing {

	// Fields

	@Autowired
	private WebApplicationContext context;

	private MockMvc mockMvc;


	@BeforeEach
	void setUp(RestDocumentationContextProvider restDocumentation) {
		this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
			.apply(documentationConfiguration(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.

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.extension.ExtendWith;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.ApplicationContext;
import org.springframework.restdocs.RestDocumentationContextProvider;
import org.springframework.restdocs.RestDocumentationExtension;
import org.springframework.test.web.reactive.server.WebTestClient;

import static org.springframework.restdocs.operation.preprocess.Preprocessors.modifyHeaders;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;
import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.documentationConfiguration;

@ExtendWith(RestDocumentationExtension.class)
class EveryTestPreprocessing {

	// Fields

	@Autowired
	private ApplicationContext context;

	private WebTestClient webTestClient;


	@BeforeEach
	void setUp(RestDocumentationContextProvider restDocumentation) {
		this.webTestClient = WebTestClient.bindToApplicationContext(this.context)
			.configureClient()
			.filter(documentationConfiguration(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.

Various built-in preprocessors, including those illustrated above, are available through the static methods on Preprocessors. See below for further details.

Preprocessors

Pretty Printing

prettyPrint on Preprocessors formats the content of the request or response to make it easier to read.

Masking Links

If you are documenting a hypermedia-based API, you may want to encourage clients to navigate the API by using links rather than through the use of hard coded URIs. One way to do so is to limit the use of URIs in the documentation. maskLinks on Preprocessors replaces the href of any links in the response with …. You can also specify a different replacement if you wish.

Modifying Headers

You can use modifyHeaders on Preprocessors to add, set, and remove request or response headers.

Replacing Patterns

replacePattern on Preprocessors provides a general purpose mechanism for replacing content in a request or response. Any occurrences that match a regular expression are replaced.

Modifying URIs

If you use MockMvc or a WebTestClient that is not bound to a server, you should customize URIs by changing the configuration.

You can use modifyUris on Preprocessors to modify any URIs in a request or a response. When using WebTestClient bound to a server, this lets you customize the URIs that appear in the documentation while testing a local instance of the service.

Writing Your Own Preprocessor

If one of the built-in preprocessors does not meet your needs, you can write your own by implementing the OperationPreprocessor interface. You can then use your custom preprocessor in exactly the same way as any of the built-in preprocessors.

If you want to modify only the content (body) of a request or response, consider implementing the ContentModifier interface and using it with the built-in ContentModifyingOperationPreprocessor.