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.

Your thoughts are welcome

This site uses Akismet to reduce spam. Learn how your comment data is processed.