Hotwire Tech Blog

Scribes from Hotwire Engineering

Why you should automate your documentation

What is the difference between great web service and ordinary one? In fact, there are a lot of distinctions, but one of the most significant is, of course, documentation.

This is the first thing the users see when start using your web service, and, possibly, they will never go deeper to your source code and never see how cool it is. In this case the first impression is really valuable.

I think, you’ll agree with me, that poor documentation leaves dramatically poor impression, and decrease the pleasure of using any service. It also can erase all of the greatest advantages of your service.

It is pretty straightforward, but at the same time it is true.

BUT, keeping traditional documentation up-to-date with service code is a real pain for all – QAs, developers, BAs. It is extremely hard not to forget after each change to update documentation.  OK, if it is only one response in your example, probably it is not so crucial. If you have more than 3 request/response examples, I think, you’ll agree with me.

So, the solution is – to automate the update process of documentation.

What is Spring REST Docs?

There are a lot of tools for documentation automation: Swagger, RAML, etc

One, an official Spring project, is SpringREST Docs

Spring REST Docs helps you to document RESTful services. It combines hand-written documentation done with AsciiDoctor and auto-generated snippets produced with Spring MVC Test. This approach frees you from the limitations imposed by tools like Swagger:

  • Swagger requires a lot of annotations. It’s awkward to include the descriptive text you want in an API document in annotations.
  • Swagger doesn’t support hypermedia at all
  • It is really simple to make changes in your code that Swagger will not recognized. Because it’s method of inspection can lag behind your code.

On other hand, Spring REST Docs helps you to produce documentation that is accurate, concise, and well-structured. This documentation allows your users to get the information they need with a minimum fuss.


Why Spring REST Docs?

  • First and the main argument: this is automated documentation; there is no need to update it manually
  • It is really simple to include it to your project structure using Maven/Gradle
  • It is always up to date (it refreshes it after each application redeploy, or in any other build phase)
  • It is always correct and “working” (it is generated via integration tests with some assertions, that’s why when we receive incorrect response for any reason, IT will not pass, application will not be redeployed, documentation will not be updated with errors)
  • It requires only “skeleton” to be hard coded – everything else is generated automatically
  • This tool is not dictating you how to design your API to be able to automate the process of updating documentation. It just does its job really well.
  • It is always with application – generated html doc is in the target/build folder together with application artifacts
  • It allows everyone to be developer, not writer, who just manually updates markdown document
  • And the last thing – all you need to obtain great documentation – just write the proper test


Example of the test



Example of the documentation skeleton


Example of the documentation



So if you’re wondering, how to document your API smoothly, you should definitively check out Spring REST Docs. As for our team, we have tried it in several microservices and really enjoyed it. We received positive reviews from stakeholders. A good, clear, up-to-date documentation is a crucial step on the path to success, and this fact should not be underestimated.