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!

Parameterizing the Output Directory

You can parameterize the output directory used by document. The following parameters are supported:

Parameter Description

{methodName}

The unmodified name of the test method.

{method-name}

The name of the test method, formatted using kebab-case.

{method_name}

The name of the test method, formatted using snake_case.

{ClassName}

The unmodified simple name of the test class.

{class-name}

The simple name of the test class, formatted using kebab-case.

{class_name}

The simple name of the test class, formatted using snake_case.

{step}

The count of calls made to the service in the current test.

For example, document("{class-name}/{method-name}") in a test method named creatingANote on the test class GettingStartedDocumentation writes snippets into a directory named getting-started-documentation/creating-a-note.

A parameterized output directory is particularly useful in combination with a @BeforeEach method. It lets documentation be configured once in a setup method and then reused in every test in the class. The following examples show how to do so:

  • 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.document;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;

@ExtendWith(RestDocumentationExtension.class)
class ParameterizedOutput {

	// Fields

	private MockMvc mockMvc;

	@Autowired
	private WebApplicationContext context;


	@BeforeEach
	void setUp(RestDocumentationContextProvider restDocumentation) {
		this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
			.apply(documentationConfiguration(restDocumentation))
			.alwaysDo(document("{method-name}/{step}/"))
			.build();
	}

}
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.webtestclient.WebTestClientRestDocumentation.document;
import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.documentationConfiguration;

@ExtendWith(RestDocumentationExtension.class)
class ParameterizedOutput {

	// Fields

	private WebTestClient webTestClient;

	@Autowired
	private ApplicationContext context;


	@BeforeEach
	void setUp(RestDocumentationContextProvider restDocumentation) {
		this.webTestClient = WebTestClient.bindToApplicationContext(this.context)
			.configureClient()
			.filter(documentationConfiguration(restDocumentation))
			.entityExchangeResultConsumer(document("{method-name}/{step}"))
			.build();
	}

}

With this configuration in place, every call to the service you are testing produces the default snippets without any further configuration. Take a look at the GettingStartedDocumentation classes in each of the sample applications to see this functionality in action.