Customizing the Output

Customizing the Generated Snippets

Spring REST Docs uses Mustache templates to produce the generated snippets. Default templates are provided for each of the snippets that Spring REST Docs can produce. To customize a snippet’s content, you can provide your own template.

Templates are loaded from the classpath from an org.springframework.restdocs.templates subpackage. The name of the subpackage is determined by the ID of the template format that is in use. The default template format, Asciidoctor, has an ID of asciidoctor, so snippets are loaded from org.springframework.restdocs.templates.asciidoctor. Each template is named after the snippet that it produces. For example, to override the template for the curl-request.adoc snippet, create a template named curl-request.snippet in src/test/resources/org/springframework/restdocs/templates/asciidoctor.

Including Extra Information

There are two ways to provide extra information for inclusion in a generated snippet:

Use the attributes method on a descriptor to add one or more attributes to it.
Pass in some attributes when calling curlRequest, httpRequest, httpResponse, and so on. Such attributes are associated with the snippet as a whole.

Any additional attributes are made available during the template rendering process. Coupled with a custom snippet template, this makes it possible to include extra information in a generated snippet.

A concrete example is the addition of a constraints column and a title when documenting request fields. The first step is to provide a constraints attribute for each field that you document and to provide a title attribute. The following examples show how to do so:

MockMvc
WebTestClient

import org.junit.jupiter.api.Test;

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

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.post;
import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.requestFields;
import static org.springframework.restdocs.snippet.Attributes.attributes;
import static org.springframework.restdocs.snippet.Attributes.key;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

class IncludingExtraInformation {

	// Fields

	private MockMvc mockMvc;


	@Test
	void test() throws Exception {
		this.mockMvc.perform(post("/users/").accept(MediaType.APPLICATION_JSON))
			.andExpect(status().isOk())
			.andDo(document("create-user", requestFields(attributes(key("title").value("Fields for user creation")), (1)
					fieldWithPath("name").description("The user's name")
						.attributes(key("constraints").value("Must not be null. Must not be empty")), (2)
					fieldWithPath("email").description("The user's email address")
						.attributes(key("constraints").value("Must be a valid email address"))))); (3)
	}

}

1	Configure the `title` attribute for the request fields snippet.
2	Set the `constraints` attribute for the `name` field.
3	Set the `constraints` attribute for the `email` field.

import org.junit.jupiter.api.Test;

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

import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.requestFields;
import static org.springframework.restdocs.snippet.Attributes.attributes;
import static org.springframework.restdocs.snippet.Attributes.key;
import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document;

class IncludingExtraInformation {

	// Fields

	private WebTestClient webTestClient;


	@Test
	void test() {
		this.webTestClient.get()
			.uri("user/5")
			.accept(MediaType.APPLICATION_JSON)
			.exchange()
			.expectStatus()
			.isOk()
			.expectBody()
			.consumeWith(document("create-user",
					requestFields(attributes(key("title").value("Fields for user creation")), (1)
							fieldWithPath("name").description("The user's name")
								.attributes(key("constraints").value("Must not be null. Must not be empty")), (2)
							fieldWithPath("email").description("The user's email address")
								.attributes(key("constraints").value("Must be a valid email address"))))); (3)
	}

}

1	Configure the `title` attribute for the request fields snippet.
2	Set the `constraints` attribute for the `name` field.
3	Set the `constraints` attribute for the `email` field.

The second step is to provide a custom template named request-fields.snippet that includes the information about the fields' constraints in the generated snippet’s table and adds a title.

.{{title}} (1)
|===
|Path|Type|Description|Constraints (2)

{{#fields}}
|{{path}}
|{{type}}
|{{description}}
|{{constraints}} (3)

{{/fields}}
|===