Spring REST Docs support

About

Spring REST Docs allows the developer to write API documentation using information recorded in test cases. These ensure that the examples in the documentation work with the current version of the code.

When running the tests, Sprig REST Docs creates a folder generated-snippets with the recorded examples. The developer can reference these snippets in the documentation.

This plugin supports the developers writing when documenting their Spring REST Docs.

Pre-Requisites

You need to upgrade to version 0.30.6 or later of the plugin. Initial support has been added in issue #312.

Detection of Spring REST Docs

The plugin will auto-detect Spring REST Docs by the folder generated-snippets when running tests. Gradle creates it the build folder. Maven created in the target folder. The current file being edited must be in a folder in or below the Gradle build.gradle or Maven pom.xml file.

Support provided by the plugin

Once the plugin detects Spring REST Docs it

• sets the snippets attribute to the generated snippets folder, therefore includes like this work:

  include::{snippets}/headers-example/response-headers.adoc[]

• activates the operation:xxx[] macro, therefore the following works:

  operation::index-example[snippets='response-fields,http-response,links']

Example project

The Spring REST Docs projects provides an example project how to set up things: https://github.com/spring-projects/spring-restdocs/tree/master/samples/rest-notes-spring-hateoas

As the editor support requires the generated-snippets folder to be present, you’ll need to run your tests to create and populate it first before the editor support activates.