Last year I found out about spring restdocs, I really liked the idea so I created a small example and I wrote a post about it. That example is a simple REST service that exposes one resource and allows only GET operation on it. Last week I started a personal project that is also a REST service but exposes more resources and allows more HTTP operations on them so it is much better suited for a post about spring restdocs. In previous post I described all steps needed to setup a project for spring restdocs so in this one I will not repeat them and I will focus only in differences between them.

The first difference is related with how to run junit tests in a spring-boot project. In version 1.3.5.RELEASE it was like below:

and in version 1.4.3.RELEASE it changed to:

The second difference is how RestDocumentation junit rule is configured with the output directory into which generated snippets should be written. It changed from:

into:

In previous post I documented request parameters and response fields, in this post I will document path parameters, request fields, response fields and response headers.

One of the resources of this project is /users/{user}/books which:

  • returns all books for provided user on GET operation
  • adds a new book for provided user on POST operation

Return all books for provided user

This method needs to document path parameters and response fields:

and generated documentation looks like:

retrieve-user-books-image

Add a new book for provided user on POST operation

This method needs to document path parameters, field fields, response headers and response fields:

and generated documentation looks like:

add-user-book-image

All the other resources and operations from this project are similar with these two and it does not make sense to repeat the information. I hope you found this post usefull and if you want all details, you can check the code and the entire generated documentation.