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

Sample	Build system	Description
REST Assured	Gradle	Demonstrates the use of Spring REST Docs with REST Assured.
Slate	Gradle	Demonstrates the use of Spring REST Docs with Markdown and Slate.
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.
TestNG	Gradle	Demonstrates the use of Spring REST Docs with TestNG.

Sample

Build system

Description

REST Assured

Gradle

Demonstrates the use of Spring REST Docs with REST Assured.

Slate

Gradle

Demonstrates the use of Spring REST Docs with Markdown and Slate.

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.

TestNG

Gradle

Demonstrates the use of Spring REST Docs with TestNG.

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.1.0.RC1</version>
    <scope>test</scope>
</dependency>

<properties> (2)
    <snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
</properties>

<build>
    <plugins>
        <plugin> (3)
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <configuration>
                <includes>
                    <include>**/*Documentation.java</include>
                </includes>
            </configuration>
        </plugin>
        <plugin> (4)
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>1.5.2</version>
            <executions>
                <execution>
                    <id>generate-docs</id>
                    <phase>prepare-package</phase> (6)
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                    <configuration>
                        <backend>html</backend>
                        <doctype>book</doctype>
                        <attributes>
                            <snippets>${snippetsDirectory}</snippets> (5)
                        </attributes>
                    </configuration>
                </execution>
            </executions>
        </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` instead.
2	Configure a property to define the output location for generated snippets.
3	Add the SureFire plugin and configure it to include files whose names end with `Documentation.java`.
4	Add the Asciidoctor plugin
5	Define an attribute named `snippets` that can be used when including the generated snippets in your documentation.
6	Using `prepare-package` allows the documentation to be included in the package.

Gradle

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

dependencies { (2)
    testCompile 'org.springframework.restdocs:spring-restdocs-mockmvc:1.1.0.RC1'
}

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

test { (4)
    outputs.dir snippetsDir
}

asciidoctor { (5)
    attributes 'snippets': snippetsDir (6)
    inputs.dir snippetsDir (7)
    dependsOn test (8)
}

1	Apply the Asciidoctor plugin.
2	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` instead.
3	Configure a property to define the output location for generated snippets.
4	Configure the `test` task to add the snippets directory as an output.
5	Configure the `asciidoctor` task
6	Define an attribute named `snippets` that can be used when including the generated snippets in your documentation.
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. The JUnitRestDocumentation rule is configured with the output directory into which generated snippets should be written. This output directory should match the snippets directory that you have configured in your build.gradle or pom.xml file.

For Maven (pom.xml that will typically be target/generated-snippets and for Gradle (build.gradle) it will typically be build/generated-snippets:

Maven

@Rule
public JUnitRestDocumentation restDocumentation =
		new JUnitRestDocumentation("target/generated-snippets");

Gradle

@Rule
public JUnitRestDocumentation restDocumentation =
		new JUnitRestDocumentation("build/generated-snippets");

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 `org.springframework.restdocs.restassured.RestAssuredRestDocumentation`.

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:

Maven

private ManualRestDocumentation restDocumentation =
		new ManualRestDocumentation("target/generated-snippets");

Gradle

private ManualRestDocumentation restDocumentation =
		new ManualRestDocumentation("build/generated-snippets");

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 `org.springframework.restdocs.restassured.RestAssuredRestDocumentation`.
4	Invoke the root (`/`) of the service.
5	Assert that the service produce the expected response.

By default, four 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

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

Using the snippets

The generated snippets can be included in your documentation using the include macro. The snippets attribute specified 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.

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. For example:

MockMvc

this.mockMvc.perform(get("/user/5").accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isOk())
    .andDo(document("index", responseFields( (1)
            fieldWithPath("contact").description("The user's contact details"), (2)
            fieldWithPath("contact.email").description("The user's email address")))); (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`. Uses the static `fieldWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`.
3	Expect a field with the path `contact.email`.

REST Assured

RestAssured.given(this.spec).accept("application/json")
    .filter(document("user", responseFields( (1)
            fieldWithPath("contact").description("The user's contact details"), (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`. Uses the static `fieldWithPath` method on `org.springframework.restdocs.payload.PayloadDocumentation`.
3	Expect a field with the path `contact.email`.

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. For payloads with a hierarchical structure, documenting a field is sufficient for all of its descendants to also be treated as having been documented.

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

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.

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