Testing and Generate Documentation for RESTful APIs using Spring REST Docs with Kotlin and Spring-Boot
Documenting APIs could be a pain task, if you are not using a framework to do it. The chances to leaving docs out of date are elevated. To avoid this scenario, there are some alternatives, like Swagger and, the purpose of this post, Spring REST Docs.
I’m using Swagger in some projects and I like it, given the facility to use. For who doesn’t know, how to document APIs using Swagger, here is the steps. You will need to include a dependency in your Project and so configure your Application class to enable Swagger. Given this configuration, just include some annotations on your Controller, to generate documentation. Following this order, first step is build the API and after, or at the same moment, add annotations on your Controller class, to automatically generate docs. Maybe I can write a post with an example to illustrate, but is easy to find some practical examples in our friend Google.
Why use Spring REST Docs instead of Swagger?
The motivation of use Spring REST Docs, emerged from a need in one Project to create APIs, add behavior tests and generate documentation of it, all in one same process. Given a necessity of an API, we can write the test and his contract in the form of documentation. It would be a way of develop based on tests.
Besides that, Spring REST Docs generate a documentation in a format more professionally, compared with Swagger. Do you agree?
See a real example of Spring REST Docs: https://docs.spring.io/spring-restdocs/docs/current/reference/html5/
Just remembering, Spring REST Docs use Asciidoctor by default.
Hands-On
To exemplify the use of Spring REST Docs, we will create a Demo API, with a simple CRUD of Products, using Spring-Boot with Kotlin. Create the Project is a simple step, made via https://start.spring.io/. Don’t forget to add, Web and REST Docs dependencies, like bellow:
Click to ‘Generate Project’, so unzip the content and open with your favorite IDE. We will create a Controller layer with all resources for our CRUD of Products:
And a Service layer, necessary to explain the use of Mock in our tests later:
Now we need to add a configuration required to use Spring REST Docs. Basically, we need to add two plugins in our plugins section in our pom.xml
1 — asciidoctor-maven-plugin: Required to generate and package all documentation Snippets.
2 — maven-resources-plugin: Required to copy generated docs to folder ‘generated-docs’.
Configurations made, time for write our scenario of test, including at this point, a documentation wished.
Testing and Documenting our Controller layer with Spring REST Docs
Look at setup function, required to generate our documentation. Besides this, look at function shouldCreateProduct, where our scenario is written, using Mockito to mock the service Layer. After, we were written the call to API including all parameters required in the request.
After write the Class, we can build and execute the tests to see all snippets generated by Spring REST Docs in our target folder with the same name of test class and function class.
Now we can customize file at /src/main/asciidoc/index.adoc, including all snippets and organizing like we wish.
Based on plugins that we added and configured, it will be converted in a filename index.html that will be available at path: http://localhost:8080/docs/index.html
See our index.adoc code: https://gist.github.com/thiagotn/556fd14584c01cd00141910b019d99f8
At this point, we can build and run our project:
mvn clean install
mvn spring-boot:run
And access http://localhost:8080/docs/index.html to see this result:
Do you liked this post? The completed source-code is available at my GitHub: https://github.com/thiagotn/demo-api. Feel free to improve and share.
