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.