The primary goal of the project is to make it easy to document RESTful services by combining content that's been hand-written using AsciiDoctor with auto-generated examples produced with the Spring MVC Test framework. The result is intended to be an easy-to-read user guide, akin to GitHub's API documentation for example, rather than the fully automated, dense API documentation produced by tools like Swagger.
For a broader introduction see the Documenting RESTful APIs presentation.
The project requires Java 7 or later. It's built with Gradle:
$ ./gradlew build install
Once the main project's built, take a look at one of the two sample projects. Both
projects implement a RESTful service for creating tagged notes but have different
implementations: rest-notes-spring-hateoas is implemented using Spring MVC and Spring
Hateoas while rest-notes-spring-data-rest is implemented using Spring Data REST.
To see the sample project's documentation move into its directory and use Gradle to build the documentation. For example:
$ cd rest-notes-spring-data-rest
$ ./gradlew restDocumentation
Once the build is complete, open one of the following:
- build/asciidoc/getting-started-guide.html
- build/asciidoc/api-guide.html
Every example request and response in the documentation is auto-generated using custom Spring MVC Test result handlers. This ensures that the examples match the service that they are documenting.
There are three main pieces involved in using this project to document your RESTful service.
A Gradle plugin is provided. This plugin builds on top of the AsciiDoctor plugin and is responsible for producing the documentation during the build. Assuming you've built and installed the project as described in the quick start, the plugin as configured in your project as follows:
buildscript {
repositories {
mavenLocal()
jcenter()
}
dependencies {
classpath 'org.springframework.restdocs:spring-restdocs-gradle-plugin:0.1.0.BUILD-SNAPSHOT'
}
}
apply plugin: 'org.springframework.restdocs'Spring's MVC Test framework is used to make requests to the service that you are
documenting. Any such request wrapped in a call to RestDocumentation.document will
produce individual documentation snippets for its request and its response as well as
a snippet that contains both its request and its response.
You can configure the scheme, host, and port of any URIs that appear in the documentation snippets:
@Before
public void setUp() {
this.mockMvc = MockMvcBuilders
.webAppContextSetup(this.context)
.apply(new RestDocumentationConfiguration()
.withScheme("https")
.withHost("localhost")
.withPort(8443))
.build();
}The default values are http, localhost, and 8080. You can omit the above
configuration if these defaults meet your needs.
To document a MockMvc call, you use MockMvc's andDo method, passing it a
RestDocumentationResultHandler that can be easily obtained from
the static RestDocumentation.document method:
public void getIndex() {
this.mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
.andDo(document("index"));
}The code above will perform a GET request against the index (/) of the service with
an accept header indicating that a JSON response is required. It will write the cURL
command for the request and the resulting response to files in a directory named
index in the project's build/generated-documentation/ directory. Three files will
be written:
index/request.asciidocindex/response.asciidocindex/request-response.asciidoc
Producing high-quality, easily readable documentation is difficult and the process is
only made harder by trying to write the documentation in an ill-suited format such as
Java annotations. This project addresses this by allowing you to write the bulk of
your documentation's text as an Asciidoc document. These files should be placed in
src/documentation/asciidoc.
To include the programmatically generated snippets in your documentation, you use
Asciidoc's include macro. The Gradle plugin provides an attribute, generated,
that you can use to reference the directory to which the snippets are written. For
example, to include both the request and response snippets described above:
include::{generated}/index/request.asciidoc[]
include::{generated}/index/response.asciidoc[]
To learn more, take a look at the accompanying sample projects: