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. Asciidoctor processes plain text and produces HTML, styled and layed out to suit your needs.

Spring REST Docs makes use of snippets produced by tests written with Spring MVC Test. 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, there are two sample applications available. One sample uses Spring HATEOAS and the other uses Spring Data REST. Both samples use Spring REST Docs to produce a detailed API guide and a getting started walkthrough.

Each sample contains a file named api-guide.adoc that produces an API guide for the service, and a file named getting-started-guide.adoc that produces a getting started guide that provides an introductory walkthrough.

The code that produces the generated snippets can be found in src/test/java. ApiDocumentation.java produces the snippets for the API guide. GettingStartedDocumentation.java produces the snippets for the getting started guide.

Build configuration

The first step in using Spring REST Docs is to configure your project’s build.

Gradle build configuration

The Spring HATEOAS sample contains a build.gradle file that you may wish to use as a reference. The key parts of the configuration are described below.

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

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

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.
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. You can do so by configuring the jar task to depend on the asciidoctor task and to copy the generated documentation into the jar’s static directory:

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

Maven build configuration

The Spring Data REST sample contains a pom.xml file that you may wish to use as a reference. The key parts of the configuration are described below.

<dependency> (1)
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
    <version>1.0.1.RELEASE</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>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.
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	If you want to package the documentation in your project’s jar you should use the `prepare-package` phase.

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.

First, configure the Asciidoctor plugin so that it runs in the prepare-package phase, as described above. Now configure Maven’s resources plugin to copy the generated documentation into a location where it’ll be included in the project’s jar:

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

Generating documentation snippets

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

Setting up Spring MVC test

The first step in generating documentation snippets is to declare a public RestDocumentation field that’s annotated as a JUnit @Rule. The RestDocumentation 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:

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

And for Gradle (build.gradle) it will typically be build/generated-snippets:

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

Next, provide an @Before method that creates a MockMvc instance:

@Autowired
private WebApplicationContext context;

private MockMvc mockMvc;

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

The MockMvc instance is configured using a RestDocumentationMockMvcConfigurer. An instance of this class can be obtained from the static documentationConfiguration() method on org.springframework.restdocs.mockmvc.MockMvcRestDocumentation. RestDocumentationMockMvcConfigurer applies sensible defaults and also provides an API for customizing the configuration. Refer to the configuration section for more information.

Invoking the RESTful service

Now that a MockMvc instance has been created, it can be used to invoke the RESTful service and document the request and response. For example:

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

By default, three snippets a written:

<output-directory>/index/curl-request.adoc
<output-directory>/index/http-request.adoc
<output-directory>/index/http-response.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:

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

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

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:

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

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.

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:

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

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