Spring REST Docs

Document RESTful services by combining hand-written documentation with auto-generated snippets produced with Spring MVC Test, WebTestClient, or REST Assured.

Introduction

The aim of Spring REST Docs is to help you produce accurate and readable documentation for your RESTful services.

Writing high-quality documentation is difficult. One way to ease that difficulty is to use tools that are well-suited to the job. To this end, Spring REST Docs uses Asciidoctor by default. Asciidoctor processes plain text and produces HTML, styled and laid out to suit your needs. If you prefer, you can also configure Spring REST Docs to use Markdown.

Spring REST Docs uses snippets produced by tests written with Spring MVC’s test framework, Spring WebFlux’s WebTestClient or REST Assured 3. This test-driven approach helps to guarantee the accuracy of your service’s documentation. If a snippet is incorrect, the test that produces it fails.

Documenting a RESTful service is largely about describing its resources. Two key parts of each resource’s description are the details of the HTTP requests that it consumes and the HTTP responses that it produces. Spring REST Docs lets you work with these resources and the HTTP requests and responses, shielding your documentation from the inner-details of your service’s implementation. This separation helps you document your service’s API rather than its implementation. It also frees you to evolve the implementation without having to rework the documentation.

Getting started

This section describes how to get started with Spring REST Docs.

Sample Applications

If you want to jump straight in, a number of sample applications are available:

Table 1. MockMvc
Sample	Build system	Description
Spring Data REST	Maven	Demonstrates the creation of a getting started guide and an API guide for a service implemented by using Spring Data REST.
Spring HATEOAS	Gradle	Demonstrates the creation of a getting started guide and an API guide for a service implemented by using Spring HATEOAS.

Table 2. WebTestClient
Sample	Build system	Description
WebTestClient	Gradle	Demonstrates the use of Spring REST docs with Spring WebFlux’s WebTestClient.

Table 3. REST Assured
Sample	Build system	Description
REST Assured	Gradle	Demonstrates the use of Spring REST Docs with REST Assured.

Table 4. Advanced
Sample	Build system	Description
Slate	Gradle	Demonstrates the use of Spring REST Docs with Markdown and Slate.
TestNG	Gradle	Demonstrates the use of Spring REST Docs with TestNG.
JUnit 5	Gradle	Demonstrates the use of Spring REST Docs with JUnit 5.

Requirements

Spring REST Docs has the following minimum requirements:

Java 8
Spring Framework 5 (5.0.2 or later)

Additionally, the spring-restdocs-restassured module requires REST Assured 3.0.

Build configuration

The first step in using Spring REST Docs is to configure your project’s build. The Spring HATEOAS and Spring Data REST samples contain a build.gradle and pom.xml, respectively, that you may wish to use as a reference. The key parts of the configuration are described in the following listings:

Maven

<dependency> (1)
	<groupId>org.springframework.restdocs</groupId>
	<artifactId>spring-restdocs-mockmvc</artifactId>
	<version>{project-version}</version>
	<scope>test</scope>
</dependency>

<build>
	<plugins>
		<plugin> (2)
			<groupId>org.asciidoctor</groupId>
			<artifactId>asciidoctor-maven-plugin</artifactId>
			<version>1.5.8</version>
			<executions>
				<execution>
					<id>generate-docs</id>
					<phase>prepare-package</phase> (3)
					<goals>
						<goal>process-asciidoc</goal>
					</goals>
					<configuration>
						<backend>html</backend>
						<doctype>book</doctype>
					</configuration>
				</execution>
			</executions>
			<dependencies>
				<dependency> (4)
					<groupId>org.springframework.restdocs</groupId>
					<artifactId>spring-restdocs-asciidoctor</artifactId>
					<version>{project-version}</version>
				</dependency>
			</dependencies>
		</plugin>
	</plugins>
</build>

1	Add a dependency on `spring-restdocs-mockmvc` in the `test` scope. If you want to use `WebTestClient` or REST Assured rather than MockMvc, add a dependency on `spring-restdocs-webtestclient` or `spring-restdocs-restassured` respectively instead.
2	Add the Asciidoctor plugin.
3	Using `prepare-package` allows the documentation to be included in the package.
4	Add `spring-restdocs-asciidoctor` as a dependency of the Asciidoctor plugin. This will automatically configure the `snippets` attribute for use in your `.adoc` files to point to `target/generated-snippets`. It will also allow you to use the `operation` block macro.

Gradle

plugins { (1)
	id "org.asciidoctor.jvm.convert" version "3.3.2"
}

configurations {
	asciidoctorExt (2)
}

dependencies {
	asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor:{project-version}' (3)
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc:{project-version}' (4)
}

ext { (5)
	snippetsDir = file('build/generated-snippets')
}

test { (6)
	outputs.dir snippetsDir
}

asciidoctor { (7)
	inputs.dir snippetsDir (8)
	configurations 'asciidoctorExt' (9)
	dependsOn test (10)
}

1	Apply the Asciidoctor plugin.
2	Declare the `asciidoctorExt` configuration for dependencies that extend Asciidoctor.
3	Add a dependency on `spring-restdocs-asciidoctor` in the `asciidoctorExt` configuration. This will automatically configure the `snippets` attribute for use in your `.adoc` files to point to `build/generated-snippets`. It will also allow you to use the `operation` block macro.
4	Add a dependency on `spring-restdocs-mockmvc` in the `testImplementation` configuration. If you want to use `WebTestClient` or REST Assured rather than MockMvc, add a dependency on `spring-restdocs-webtestclient` or `spring-restdocs-restassured` respectively instead.
5	Configure a property to define the output location for generated snippets.
6	Configure the `test` task to add the snippets directory as an output.
7	Configure the `asciidoctor` task.
8	Configure the snippets directory as an input.
9	Configure the use of the `asciidoctorExt` configuration for extensions.
10	Make the task depend on the test task so that the tests are run before the documentation is created.

Packaging the Documentation

You may want to package the generated documentation in your project’s jar file — for example, to have it served as static content by Spring Boot. To do so, configure your project’s build so that:

The documentation is generated before the jar is built
The generated documentation is included in the jar

The following listings show how to do so in both Maven and Gradle:

Maven

<plugin> (1)
	<groupId>org.asciidoctor</groupId>
	<artifactId>asciidoctor-maven-plugin</artifactId>
	<!-- … -->
</plugin>
<plugin> (2)
	<artifactId>maven-resources-plugin</artifactId>
	<version>2.7</version>
	<executions>
		<execution>
			<id>copy-resources</id>
			<phase>prepare-package</phase>
			<goals>
				<goal>copy-resources</goal>
			</goals>
			<configuration> (3)
				<outputDirectory>
					${project.build.outputDirectory}/static/docs
				</outputDirectory>
				<resources>
					<resource>
						<directory>
							${project.build.directory}/generated-docs
						</directory>
					</resource>
				</resources>
			</configuration>
		</execution>
	</executions>
</plugin>

1	The existing declaration for the Asciidoctor plugin.
2	The resource plugin must be declared after the Asciidoctor plugin as they are bound to the same phase (`prepare-package`) and the resource plugin must run after the Asciidoctor plugin to ensure that the documentation is generated before it’s copied.
3	Copy the generated documentation into the build output’s `static/docs` directory, from where it will be included in the jar file.

Gradle

bootJar {
	dependsOn asciidoctor (1)
	from ("${asciidoctor.outputDir}/html5") { (2)
		into 'static/docs'
	}
}

1	Ensure that the documentation has been generated before the jar is built.
2	Copy the generated documentation into the jar’s `static/docs` directory.

Generating Documentation Snippets

Spring REST Docs uses Spring MVC’s test framework, Spring WebFlux’s WebTestClient, or REST Assured to make requests to the service that you are documenting. It then produces documentation snippets for the request and the resulting response.

Setting up Your Tests

Exactly how you set up your tests depends on the test framework that you use. Spring REST Docs provides first-class support for JUnit 4 and JUnit 5. Other frameworks, such as TestNG, are also supported, although slightly more setup is required.

Setting up Your JUnit 4 Tests

When using JUnit 4, the first step in generating documentation snippets is to declare a public JUnitRestDocumentation field that is annotated as a JUnit @Rule. The following example shows how to do so:

@Rule
public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();

By default, the JUnitRestDocumentation rule is automatically configured with an output directory based on your project’s build tool:

Build tool Output directory

Build tool	Output directory
Maven	`target/generated-snippets`
Gradle	`build/generated-snippets`

Maven

target/generated-snippets

Gradle

build/generated-snippets

You can override the default by providing an output directory when you create the JUnitRestDocumentation instance. The following example shows how to do so:

@Rule
public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("custom");

Next, you must provide an @Before method to configure MockMvc, WebTestClient or REST Assured. The following examples show how to do so:

MockMvc

private MockMvc mockMvc;

@Autowired
private WebApplicationContext context;

@Before
public void setUp() {
	this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
			.apply(documentationConfiguration(this.restDocumentation)) (1)
			.build();
}

1	The `MockMvc` instance is configured by using a `MockMvcRestDocumentationConfigurer`. You can obtain an instance of this class from the static `documentationConfiguration()` method on `org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`.

WebTestClient

private WebTestClient webTestClient;

@Autowired
private ApplicationContext context;

@Before
public void setUp() {
	this.webTestClient = WebTestClient.bindToApplicationContext(this.context).configureClient()
			.filter(documentationConfiguration(this.restDocumentation)) (1)
			.build();
}

1 The WebTestClient instance is configured by adding a WebTestclientRestDocumentationConfigurer as an ExchangeFilterFunction. You can obtain an instance of this class from the static documentationConfiguration() method on org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.

REST Assured

private RequestSpecification spec;

@Before
public void setUp() {
	this.spec = new RequestSpecBuilder().addFilter(documentationConfiguration(this.restDocumentation)) (1)
			.build();
}

1	REST Assured is configured by adding a `RestAssuredRestDocumentationConfigurer` as a `Filter`. You can obtain an instance of this class from the static `documentationConfiguration()` method on `RestAssuredRestDocumentation` in the `org.springframework.restdocs.restassured3` package.

The configurer applies sensible defaults and also provides an API for customizing the configuration. See the configuration section for more information.

Setting up Your JUnit 5 Tests

When using JUnit 5, the first step in generating documentation snippets is to apply the RestDocumentationExtension to your test class. The following example shows how to do so:

@ExtendWith(RestDocumentationExtension.class)
public class JUnit5ExampleTests {

When testing a typical Spring application, you should also apply the SpringExtension:

@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
public class JUnit5ExampleTests {

The RestDocumentationExtension is automatically configured with an output directory based on your project’s build tool:

Build tool Output directory

Build tool	Output directory
Maven	`target/generated-snippets`
Gradle	`build/generated-snippets`

Maven

target/generated-snippets

Gradle

build/generated-snippets

If you are using JUnit 5.1, you can override the default by registering the extension as a field in your test class and providing an output directory when creating it. The following example shows how to do so:

public class JUnit5ExampleTests {

	@RegisterExtension
	final RestDocumentationExtension restDocumentation = new RestDocumentationExtension ("custom");

}

Next, you must provide a @BeforeEach method to configure MockMvc, WebTestClient, or REST Assured. The following listings show how to do so:

MockMvc

private MockMvc mockMvc;

@BeforeEach
void setUp(WebApplicationContext webApplicationContext, RestDocumentationContextProvider restDocumentation) {
	this.mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext)
			.apply(documentationConfiguration(restDocumentation)) (1)
			.build();
}

1	The `MockMvc` instance is configured by using a `MockMvcRestDocumentationConfigurer`. You can obtain an instance of this class from the static `documentationConfiguration()` method on `org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`.

WebTestClient

private WebTestClient webTestClient;

@BeforeEach
void setUp(ApplicationContext applicationContext, RestDocumentationContextProvider restDocumentation) {
	this.webTestClient = WebTestClient.bindToApplicationContext(applicationContext).configureClient()
			.filter(documentationConfiguration(restDocumentation)) (1)
			.build();
}

1 The WebTestClient instance is configured by adding a WebTestClientRestDocumentationConfigurer as an ExchangeFilterFunction. You can obtain an instance of this class from the static documentationConfiguration() method on org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.

REST Assured

private RequestSpecification spec;

@BeforeEach
void setUp(RestDocumentationContextProvider restDocumentation) {
	this.spec = new RequestSpecBuilder().addFilter(documentationConfiguration(restDocumentation)) (1)
			.build();
}

1	REST Assured is configured by adding a `RestAssuredRestDocumentationConfigurer` as a `Filter`. You can obtain an instance of this class from the static `documentationConfiguration()` method on `RestAssuredRestDocumentation` in the `org.springframework.restdocs.restassured3` package.

The configurer applies sensible defaults and also provides an API for customizing the configuration. See the configuration section for more information.

Setting up your tests without JUnit

The configuration when JUnit is not being used is largely similar to when it is being used. This section describes the key differences. The TestNG sample also illustrates the approach.

The first difference is that you should use ManualRestDocumentation in place of JUnitRestDocumentation. Also, you do not need the @Rule annotation. The following example shows how to use ManualRestDocumentation:

private ManualRestDocumentation restDocumentation = new ManualRestDocumentation();

Secondly, you must call ManualRestDocumentation.beforeTest(Class, String) before each test. You can do so as part of the method that configures MockMvc, WebTestClient, or REST Assured. The following examples show how to do so:

MockMvc

private MockMvc mockMvc;

@Autowired
private WebApplicationContext context;

@BeforeMethod
public void setUp(Method method) {
	this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
			.apply(documentationConfiguration(this.restDocumentation)).build();
	this.restDocumentation.beforeTest(getClass(), method.getName());
}

WebTestClient

private WebTestClient webTestClient;

@Autowired
private ApplicationContext context;

@BeforeMethod
public void setUp(Method method) {
	this.webTestClient = WebTestClient.bindToApplicationContext(this.context).configureClient()
			.filter(documentationConfiguration(this.restDocumentation)) (1)
			.build();
	this.restDocumentation.beforeTest(getClass(), method.getName());
}

REST Assured

private RequestSpecification spec;

@BeforeMethod
public void setUp(Method method) {
	this.spec = new RequestSpecBuilder().addFilter(documentationConfiguration(this.restDocumentation)).build();
	this.restDocumentation.beforeTest(getClass(), method.getName());
}

Finally, you must call ManualRestDocumentation.afterTest after each test. The following example shows how to do so with TestNG:

@AfterMethod
public void tearDown() {
	this.restDocumentation.afterTest();
}

Invoking the RESTful Service

Now that you have configured the testing framework, you can use it to invoke the RESTful service and document the request and response. The following examples show how to do so:

MockMvc

this.mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON)) (1)
		.andExpect(status().isOk()) (2)
		.andDo(document("index")); (3)

1	Invoke the root (`/`) of the service and indicate that an `application/json` response is required.
2	Assert that the service produced the expected response.
3	Document the call to the service, writing the snippets into a directory named `index` (which is located beneath the configured output directory). The snippets are written by a `RestDocumentationResultHandler`. You can obtain an instance of this class from the static `document` method on `org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`.

WebTestClient

this.webTestClient.get().uri("/").accept(MediaType.APPLICATION_JSON) (1)
		.exchange().expectStatus().isOk() (2)
		.expectBody().consumeWith(document("index")); (3)

1	Invoke the root (`/`) of the service and indicate that an `application/json` response is required.
2	Assert that the service produced the expected response.
3	Document the call to the service, writing the snippets into a directory named `index` (which is located beneath the configured output directory). The snippets are written by a `Consumer` of the `ExchangeResult`. You can obtain such a consumer from the static `document` method on `org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation`.

REST Assured

RestAssured.given(this.spec) (1)
		.accept("application/json") (2)
		.filter(document("index")) (3)
		.when().get("/") (4)
		.then().assertThat().statusCode(is(200)); (5)

1	Apply the specification that was initialized in the `@Before` method.
2	Indicate that an `application/json` response is required.
3	Document the call to the service, writing the snippets into a directory named `index` (which is located beneath the configured output directory). The snippets are written by a `RestDocumentationFilter`. You can obtain an instance of this class from the static `document` method on `RestAssuredRestDocumentation` in the `org.springframework.restdocs.restassured3` package.
4	Invoke the root (`/`) of the service.
5	Assert that the service produce the expected response.

By default, six snippets are written:

<output-directory>/index/curl-request.adoc
<output-directory>/index/http-request.adoc
<output-directory>/index/http-response.adoc
<output-directory>/index/httpie-request.adoc
<output-directory>/index/request-body.adoc
<output-directory>/index/response-body.adoc

See Documenting your API for more information about these and other snippets that can be produced by Spring REST Docs.

Using the Snippets

Before using the generated snippets, you must create an .adoc source file. You can name the file whatever you like as long as it has a .adoc suffix. The resulting HTML file has the same name but with a .html suffix. The default location of the source files and the resulting HTML files depends on whether you use Maven or Gradle:

Build tool Source files Generated files

Build tool	Source files	Generated files
Maven	`src/main/asciidoc/*.adoc`	`target/generated-docs/*.html`
Gradle	`src/docs/asciidoc/*.adoc`	`build/asciidoc/html5/*.html`

Maven

src/main/asciidoc/*.adoc

target/generated-docs/*.html

Gradle

src/docs/asciidoc/*.adoc

build/asciidoc/html5/*.html

You can then include the generated snippets in the manually created Asciidoc file (described earlier in this section) by using the include macro. You can use the snippets attribute that is automatically set by spring-restdocs-asciidoctor configured in the build configuration to reference the snippets output directory. The following example shows how to do so:

include::{snippets}/index/curl-request.adoc[]

Documenting your API

This section provides more details about using Spring REST Docs to document your API.

Hypermedia

Spring REST Docs provides support for documenting the links in a hypermedia-based API. The following examples show how to use it:

MockMvc

this.mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON)).andExpect(status().isOk())
		.andDo(document("index", links((1)
				linkWithRel("alpha").description("Link to the alpha resource"), (2)
				linkWithRel("bravo").description("Link to the bravo resource")))); (3)

1	Configure Spring REST docs to produce a snippet describing the response’s links. Uses the static `links` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.
2	Expect a link whose `rel` is `alpha`. Uses the static `linkWithRel` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.
3	Expect a link whose `rel` is `bravo`.

WebTestClient

this.webTestClient.get().uri("/").accept(MediaType.APPLICATION_JSON).exchange().expectStatus().isOk()
		.expectBody().consumeWith(document("index", links((1)
				linkWithRel("alpha").description("Link to the alpha resource"), (2)
				linkWithRel("bravo").description("Link to the bravo resource")))); (3)

1	Configure Spring REST docs to produce a snippet describing the response’s links. Uses the static `links` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.
2	Expect a link whose `rel` is `alpha`. Uses the static `linkWithRel` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.
3	Expect a link whose `rel` is `bravo`.

REST Assured

RestAssured.given(this.spec).accept("application/json").filter(document("index", links((1)
		linkWithRel("alpha").description("Link to the alpha resource"), (2)
		linkWithRel("bravo").description("Link to the bravo resource")))) (3)
		.get("/").then().assertThat().statusCode(is(200));

1	Configure Spring REST docs to produce a snippet describing the response’s links. Uses the static `links` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.
2	Expect a link whose `rel` is `alpha`. Uses the static `linkWithRel` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.
3	Expect a link whose `rel` is `bravo`.

The result is a snippet named links.adoc that contains a table describing the resource’s links.

If a link in the response has a title, you can omit the description from its descriptor and the title is used. If you omit the description and the link does not have a title, a failure occurs.

When documenting links, the test fails if an undocumented link is found in the response. Similarly, the test also fails if a documented link is not found in the response and the link has not been marked as optional.

If you do not want to document a link, you can mark it as ignored. Doing so prevents it from appearing in the generated snippet while avoiding the failure described above.

You can also document links in a relaxed mode, where any undocumented links do not cause a test failure. To do so, use the relaxedLinks method on org.springframework.restdocs.hypermedia.HypermediaDocumentation. This can be useful when documenting a particular scenario where you only want to focus on a subset of the links.

Hypermedia Link Formats

Two link formats are understood by default:

Atom: Links are expected to be in an array named links. This is used by default when the content type of the response is compatible with application/json.
HAL: Links are expected to be in a map named _links. This is used by default when the content type of the response is compatible with application/hal+json.

If you use Atom- or HAL-format links but with a different content type, you can provide one of the built-in LinkExtractor implementations to links. The following examples show how to do so:

MockMvc

.andDo(document("index", links(halLinks(), (1)
		linkWithRel("alpha").description("Link to the alpha resource"),
		linkWithRel("bravo").description("Link to the bravo resource"))));

1	Indicate that the links are in HAL format. Uses the static `halLinks` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.

WebTestClient

.consumeWith(document("index", links(halLinks(), (1)
		linkWithRel("alpha").description("Link to the alpha resource"),
		linkWithRel("bravo").description("Link to the bravo resource"))));

1	Indicate that the links are in HAL format. Uses the static `halLinks` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.

REST Assured

.filter(document("index", links(halLinks(), (1)
		linkWithRel("alpha").description("Link to the alpha resource"),
		linkWithRel("bravo").description("Link to the bravo resource"))))

1	Indicate that the links are in HAL format. Uses the static `halLinks` method on `org.springframework.restdocs.hypermedia.HypermediaDocumentation`.

If your API represents its links in a format other than Atom or HAL, you can provide your own implementation of the LinkExtractor interface to extract the links from the response.

Ignoring Common Links

Rather than documenting links that are common to every response, such as self and curies when using HAL, you may want to document them once in an overview section and then ignore them in the rest of your API’s documentation. To do so, you can build on the support for reusing snippets to add link descriptors to a snippet that is preconfigured to ignore certain links. The following example shows how to do so:

public static LinksSnippet links(LinkDescriptor... descriptors) {
	return HypermediaDocumentation.links(linkWithRel("self").ignored().optional(), linkWithRel("curies").ignored())
			.and(descriptors);
}

Request and Response Payloads

In addition to the hypermedia-specific support described earlier, support for general documentation of request and response payloads is also provided.

By default, Spring REST Docs automatically generates snippets for the body of the request and the body of the response. These snippets are named request-body.adoc and response-body.adoc respectively.

Request and Response Fields

To provide more detailed documentation of a request or response payload, support for documenting the payload’s fields is provided.

Consider the following payload:

{
	"contact": {
		"name": "Jane Doe",
		"email": "[email protected]"
	}
}

You can document the previous example’s fields as follows:

MockMvc

this.mockMvc.perform(get("/user/5").accept(MediaType.APPLICATION_JSON)).andExpect(status().isOk())
		.andDo(document("index", responseFields((1)
				fieldWithPath("contact.email").description("The user's email address"), (2)
				fieldWithPath("contact.name").description("The user's name")))); (3)

1	Configure Spring REST docs to produce a snippet describing the fields in the response payload. To document a request, you can use `requestFields`. Both are static methods on `org.springframework.restdocs.payload.PayloadDocumentation`.
2	Expect a field with the path `contact.email`. Uses the static `fieldWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`.
3	Expect a field with the path `contact.name`.

WebTestClient

this.webTestClient.get().uri("user/5").accept(MediaType.APPLICATION_JSON)
	.exchange().expectStatus().isOk().expectBody()
	.consumeWith(document("user",
		responseFields((1)
			fieldWithPath("contact.email").description("The user's email address"), (2)
			fieldWithPath("contact.name").description("The user's name")))); (3)

1	Configure Spring REST docs to produce a snippet describing the fields in the response payload. To document a request, you can use `requestFields`. Both are static methods on `org.springframework.restdocs.payload.PayloadDocumentation`.
2	Expect a field with the path `contact.email`. Uses the static `fieldWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`.
3	Expect a field with the path `contact.name`.

REST Assured

RestAssured.given(this.spec).accept("application/json").filter(document("user", responseFields((1)
		fieldWithPath("contact.name").description("The user's name"), (2)
		fieldWithPath("contact.email").description("The user's email address")))) (3)
		.when().get("/user/5").then().assertThat().statusCode(is(200));

1	Configure Spring REST docs to produce a snippet describing the fields in the response payload. To document a request, you can use `requestFields`. Both are static methods on `org.springframework.restdocs.payload.PayloadDocumentation`.
2	Expect a field with the path `contact.email`. Uses the static `fieldWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`.
3	Expect a field with the path `contact.name`.

The result is a snippet that contains a table describing the fields. For requests, this snippet is named request-fields.adoc. For responses, this snippet is named response-fields.adoc.

When documenting fields, the test fails if an undocumented field is found in the payload. Similarly, the test also fails if a documented field is not found in the payload and the field has not been marked as optional.

If you do not want to provide detailed documentation for all of the fields, an entire subsection of a payload can be documented. The following examples show how to do so:

MockMvc

this.mockMvc.perform(get("/user/5").accept(MediaType.APPLICATION_JSON)).andExpect(status().isOk())
		.andDo(document("index", responseFields((1)
				subsectionWithPath("contact").description("The user's contact details")))); (1)

1	Document the subsection with the path `contact`. `contact.email` and `contact.name` are now seen as having also been documented. Uses the static `subsectionWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`.

WebTestClient

this.webTestClient.get().uri("user/5").accept(MediaType.APPLICATION_JSON)
	.exchange().expectStatus().isOk().expectBody()
	.consumeWith(document("user",
		responseFields(
			subsectionWithPath("contact").description("The user's contact details")))); (1)

1	Document the subsection with the path `contact`. `contact.email` and `contact.name` are now seen as having also been documented. Uses the static `subsectionWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`.

REST Assured

RestAssured.given(this.spec).accept("application/json")
		.filter(document("user",
				responseFields(subsectionWithPath("contact").description("The user's contact details")))) (1)
		.when().get("/user/5").then().assertThat().statusCode(is(200));

1	Document the subsection with the path `contact`. `contact.email` and `contact.name` are now seen as having also been documented. Uses the static `subsectionWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`.

subsectionWithPath can be useful for providing a high-level overview of a particular section of a payload. You can then produce separate, more detailed documentation for a subsection. See Documenting a Subsection of a Request or Response Payload.

If you do not want to document a field or subsection at all, you can mark it as ignored. This prevents it from appearing in the generated snippet while avoiding the failure described earlier.

You can also document fields in a relaxed mode, where any undocumented fields do not cause a test failure. To do so, use the relaxedRequestFields and relaxedResponseFields methods on org.springframework.restdocs.payload.PayloadDocumentation. This can be useful when documenting a particular scenario where you want to focus only on a subset of the payload.

By default, Spring REST Docs assumes that the payload you are documenting is JSON. If you want to document an XML payload, the content type of the request or response must be compatible with application/xml.

Fields in JSON Payloads

This section describes how to work with fields in JSON payloads.

JSON Field Paths

JSON field paths use either dot notation or bracket notation. Dot notation uses '.' to separate each key in the path (for example, a.b). Bracket notation wraps each key in square brackets and single quotation marks (for example, ['a']['b']). In either case, [] is used to identify an array. Dot notation is more concise, but using bracket notation enables the use of . within a key name (for example, ['a.b']). The two different notations can be used in the same path (for example, a['b']).

Consider the following JSON payload:

{
	"a":{
		"b":[
			{
				"c":"one"
			},
			{
				"c":"two"
			},
			{
				"d":"three"
			}
		],
		"e.dot" : "four"
	}
}

In the preceding JSON payload, the following paths are all present:

Path Value

Path	Value
`a`	An object containing `b`
`a.b`	An array containing three objects
`['a']['b']`	An array containing three objects
`a['b']`	An array containing three objects
`['a'].b`	An array containing three objects
`a.b[]`	An array containing three objects
`a.b[].c`	An array containing the strings `one` and `two`
`a.b[].d`	The string `three`
`a['e.dot']`	The string `four`
`['a']['e.dot']`	The string `four`

a

An object containing b

a.b