Spring REST Docs

Document RESTful services by combining hand-written documentation with auto-generated snippets produced with Spring MVC Test.

Introduction

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

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 layed out to suit your needs. If you prefer, Spring REST Docs can also be configured to use Markdown.

Spring REST Docs makes use of snippets produced by tests written with Spring MVC Test or REST Assured 2 and 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 will fail.

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 allows you to 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 to 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 using Spring Data REST.
Spring HATEOAS	Gradle	Demonstrates the creation of a getting started guide and an API guide for a service implemented using Spring HATEOAS.

Table 2. REST Assured
Sample	Build system	Description
Grails	Gradle	Demonstrates the use of Spring REST docs with Grails and Spock.
REST Assured	Gradle	Demonstrates the use of Spring REST Docs with REST Assured.

Table 3. 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.

Requirements

Spring REST Docs has the following minimum requirements:

Java 7
Spring Framework 4.3

Additionally, the spring-restdocs-restassured module has the following minimum requirements:

REST Assured 2.8 (com.jayway.restassured:restassured) or REST Assured 3.0 (io.rest-assured:rest-assured)

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 below.

Maven

<dependency> (1)
	<groupId>org.springframework.restdocs</groupId>
	<artifactId>spring-restdocs-mockmvc</artifactId>
	<version>1.2.0.RELEASE</version>
	<scope>test</scope>
</dependency>

<build>
	<plugins>
		<plugin> (2)
			<groupId>org.asciidoctor</groupId>
			<artifactId>asciidoctor-maven-plugin</artifactId>
			<version>1.5.3</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>1.2.0.RELEASE</version>
				</dependency>
			</dependencies>
		</plugin>
	</plugins>
</build>

1	Add a dependency on `spring-restdocs-mockmvc` in the `test` scope. If you want to use REST Assured rather than MockMvc, add a dependency on `spring-restdocs-restassured` and `com.jayway.restassured:restassured` (REST Assured 2) or `io.rest-assured:rest-assured` (REST Assured 3) 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.convert" version "1.5.3"
}

dependencies {
	asciidoctor 'org.springframework.restdocs:spring-restdocs-asciidoctor:1.2.0.RELEASE' (2)
	testCompile 'org.springframework.restdocs:spring-restdocs-mockmvc:1.2.0.RELEASE' (3)
}

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

test { (5)
	outputs.dir snippetsDir
}

asciidoctor { (6)
	inputs.dir snippetsDir (7)
	dependsOn test (8)
}

1	Apply the Asciidoctor plugin.
2	Add a dependency on `spring-restdocs-asciidoctor` in the `asciidoctor` 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.
3	Add a dependency on `spring-restdocs-mockmvc` in the `testCompile` configuration. If you want to use REST Assured rather than MockMvc, add a dependency on `spring-restdocs-restassured` and `com.jayway.restassured:restassured` (REST Assured 2) or `io.rest-assured:rest-assured` (REST Assured 3) instead.
4	Configure a property to define the output location for generated snippets.
5	Configure the `test` task to add the snippets directory as an output.
6	Configure the `asciidoctor` task
7	Configure the snippets directory as an input.
8	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

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

jar {
	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’s MVC Test framework 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 setup your tests depends on the test framework that you’re using. Spring REST Docs provides first-class support for JUnit. Other frameworks, such as TestNG, are also supported although slightly more setup is required.

Setting up your JUnit tests

When using JUnit, the first step in generating documentation snippets is to declare a public JUnitRestDocumentation field that’s annotated as a JUnit @Rule.

@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

The default can be overridden by providing an output directory when creating the JUnitRestDocumentation instance:

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

Next, provide an @Before method to configure MockMvc or REST Assured:

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 using a `MockMvcRestDocumentationConfigurer`. An instance of this class can be obtained from the static `documentationConfiguration()` method on `org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`.

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. An instance of this class can be obtained from the static documentationConfiguration() method on RestAssuredRestDocumentation in the org.springframework.restdocs.restassured or org.springframework.restdocs.restassured3 package depending on the version of REST Assured that you are using.

The configurer applies sensible defaults and also provides an API for customizing the configuration. Refer to 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 ManualRestDocumentation should be used in place of JUnitRestDocumentation and there’s no need for the @Rule annotation:

private ManualRestDocumentation restDocumentation = new ManualRestDocumentation();

Secondly, ManualRestDocumentation.beforeTest(Class, String) must be called before each test. This can be done as part of the method that is configuring MockMVC or REST Assured:

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());
}

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());
}

Lastly, ManualRestDocumentation.afterTest must be called after each test. For example, with TestNG:

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

Invoking the RESTful service

Now that the testing framework has been configured, it can be used to invoke the RESTful service and document the request and response. For example:

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` that will be located beneath the configured output directory. The snippets are written by a `RestDocumentationResultHandler`. An instance of this class can be obtained from the static `document` method on `org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`.

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 initialised 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` that will be located beneath the configured output directory. The snippets are written by a `RestDocumentationFilter`. An instance of this class can be obtained from the static `document` method on `RestAssuredRestDocumentation` in the `org.springframework.restdocs.restassured` or `org.springframework.restdocs.restassured3` package depending on the version of REST Assured that you are using.
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

Refer to 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, a .adoc source file must be created. You can name the file whatever you like as long as it has a .adoc suffix. The result HTML file will have the same name but with a .html suffix. The default location of the source files and the resulting HTML files depends on whether you are using 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

The generated snippets can then be included in the manually created Asciidoctor file from above using the include macro. The snippets attribute that is automatically set by spring-restdocs-asciidoctor configured in the build configuration can be used to reference the snippets output directory. For example:

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:

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`.

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, the description can be omitted from its descriptor and the title will be used. If you omit the description and the link does not have a title a failure will occur.

When documenting links, the test will fail if an undocumented link is found in the response. Similarly, the test will also fail 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. This will prevent it from appearing in the generated snippet while avoiding the failure described above.

Links can also be documented in a relaxed mode where any undocumented links will 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. 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. Used by default when the content type of the response is compatible with application/hal+json.

If you are using Atom or HAL-format links but with a different content type you can provide one of the built-in LinkExtractor implementations to links. For example:

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`.

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’s preconfigured to ignore certain links. For example:

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 above, support for general documentation of request and response payloads is also provided.

By default, Spring REST Docs will automatically generate 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": "jane.doe@example.com"
	}
}

Its fields can be documented like this:

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 `requestFields` can be used. 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 `requestFields` can be used. 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 will fail if an undocumented field is found in the payload. Similarly, the test will also fail if a documented field is not found in the payload and the field has not been marked as optional.

If you don’t want to provide detailed documentation for all of the fields, an entire subsection of a payload can be documented. For example:

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 has 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));
	}

	public void explicitType() throws Exception {
		RestAssured.given(this.spec).accept("application/json")
			.filter(document("user", responseFields(
					fieldWithPath("contact.email")
							.type(JsonFieldType.STRING) (1)
							.description("The user's email address"))))
			.when().get("/user/5")
			.then().assertThat().statusCode(is(200));
	}

	public void constraints() throws Exception {
		RestAssured.given(this.spec).accept("application/json")
			.filter(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)
			.when().post("/users")
			.then().assertThat().statusCode(is(200));
	}

	public void descriptorReuse() throws Exception {
		FieldDescriptor[] book = new FieldDescriptor[] {
				fieldWithPath("title").description("Title of the book"),
				fieldWithPath("author").description("Author of the book") };

		RestAssured.given(this.spec).accept("application/json")
			.filter(document("book", responseFields(book))) (1)
			.when().get("/books/1")
			.then().assertThat().statusCode(is(200));

		RestAssured.given(this.spec).accept("application/json")
			.filter(document("books", responseFields(
				fieldWithPath("[]").description("An array of books")) (1)
				.andWithPrefix("[].", book))) (2)
			.when().get("/books")
			.then().assertThat().statusCode(is(200));
	}

	public void fieldsSubsection() throws Exception {
		RestAssured.given(this.spec).accept("application/json")
			.filter(document("location", responseFields(beneathPath("weather.temperature"), (1)
				fieldWithPath("high").description("The forecast high in degrees celcius"), (2)
				fieldWithPath("low").description("The forecast low in degrees celcius"))))
			.when().get("/locations/1")
			.then().assertThat().statusCode(is(200));
	}

	public void bodySubsection() throws Exception {
		RestAssured.given(this.spec).accept("application/json")
			.filter(document("location", responseBody(beneathPath("weather.temperature")))) (1)
			.when().get("/locations/1")
			.then().assertThat().statusCode(is(200));
	}

}

1	Document the subsection with the path `contact`. `contact.email` and `contact.name` are now seen has 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. Separate, more detailed documentation for a subsection can then be produced.

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

Fields can also be documented in a relaxed mode where any undocumented fields will 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 only want to focus on a subset of the payload.

By default, Spring REST Docs will assume 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

JSON field paths

JSON field paths use either dot notation or bracket notation. Dot notation uses '.' to separate each key in the path; a.b, for example. Bracket notation wraps each key in square brackets and single quotes; ['a']['b'], for example. 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; ['a.b'], for example. The two different notations can be used in the same path; a['b'], for example.

With this JSON payload:

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

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