What is Spring Rest Docs

Spring Rest Docs is about documenting RESTful APIs by combining hand written documentation with auto-generated snippets produced with Spring MVC Tests.

This approach is called Test Driven Documentation (TDD)

No extra annotations are needed just API live tests.

The documentation is written with Asciidoctor and payload snippets are produced by calling/testing the actual API with MockMVC.

This leads to a end to end tested API with up to date snippets (headers, requests, responses) and more fine grained control on the documentation.

Spring RestDocs is meant to produce API documentation for APIs that are greater and equal to level 2 maturity model

Example

Spring Boot Playground Project

I’ll be using a simple CRUD controller with an in memory datastore for simplicity.

Now let’s document this API.

Basic Configuration

Add the following dependency on your pom.xml

Configure a snippets directory in maven properties. This is were snippets are extracted after the live tests. Configure maven test phase to pick up and execute tests ending with Documentation.java

Configure asciidoc to pick index.adoc from default location (src/main/asciidoc) and set snippets variable to snippetsDirectory defined in maven properties

Testing Controllers with MockMVC / Generate snippets

Set up MockMVC before the tests

WebApplicationContext is needed by MockMVC so that it can figure out the path for the API.

RestDocumentation rule captures the output and writes it to the specified generated-snippets folder. Those snippets can be included

in the final RESTful API documentation using the var {snippets}.

Testing operations

Asciidoctor to combine snippets into a final deliverable

Package it with the Spring Boot application

Spring boot can serve static content ( see)

Add generated index.html to static folder in spring boot jar

Run with mvn spring-boot:run

and visit http://localhost:8080/docs/index.html

RestDocs in the future

Support for RestAssured already integrated in SNAPSHOT releaseissue

TestNG (alternative to JUnit) if only TestNG supports something like @Rule of JUnit issue

Inspired Swagger to change approach issue

Final Thoughts

Thanks for reading.

I really enjoy using Spring Restdocs. It forces me to think more about the API and places an important role on documentation. Developing with this aproach

a lot of APIs will be enhanced, become more readable and usable and as a result better ROIs.

You can download the full code from https://github.com/ssouris/spring-tutorials/tree/master/introduction-to-spring-restdocs

Resources

Spring RestDocs webinar: video

SpringOne2015 video