A Q&A with Andy Wilkinson on Spring REST Docs

Documentation is a critical, if often overlooked, aspect of any software project, and Andy Wilkinson has taken some time to answer a few questions on the newly released Spring REST Docs project.

What was the catalyst for developing Spring REST Docs?

It's largely from my experience of documenting a large RESTful service for provisioning and configuring middleware. The best tool at the time seemed to be Swagger, but its lack of hypermedia support made it a non-starter for us. We ended up rolling our own solution that was heavily inspired by Swagger with a code-first approach. Unfortunately, that was a decision that we came to regret.

The first problem we encountered was that the development experience – using lots of annotations to provide the documentation – was really unpleasant. It made me realise how important it is to use tools that are designed for the job of writing documentation. To that end, Spring REST Docs leans very heavily on Asciidoctor which allows your to use very lightweight markup to produce documentation that's structured and styled to suit your needs.

The second problem was with the Swagger-inspired structure of the documentation. It was too quick to describe things in terms of URIs (the way we, as developers of the service, were thinking about things) when what users really wanted was to see things described in terms of the problem that they were trying to solve. The structure also didn't give us anywhere to describe things that were common across the whole API such as authentication, hypermedia, and the use of HTTP verbs. That led to a lot of repetition in the documentation making the information that people were actually looking for harder to find. 

Who do you see getting the most benefit out of Spring REST Docs?

Spring REST Docs will be of most benefit to those who really care about their API's documentation and believe that it's worth expending a little bit of effort to produce documentation that's accurate and easy to use. Beyond that, I've tried really hard not to restrict Spring REST Docs' benefits unnecessarily. For example, while it's aimed at those who want to document RESTful APIs, it doesn't place any requirements on what level of maturity your API has reached. It works equally well for APIs that use hypermedia as those that don't. I see this as a big advantage over some other tools for defining and documenting RESTful APIs that can restrict your API to a particular level of maturity. When a tool you're using primarily for documentation starts dictating your API design – preventing the use of hypermedia, for example – the tool's become more of a hinderance than a help.

What was your experience like releasing Spring REST Docs as a Spring project?

A privilege, and one that I'm very grateful for. One of my favorite things about working on Spring projects is the help and input that we get from the community. Even though it is a new project, Spring REST Docs has been no different. I think that the project improved quite substantially between M1 and RC1, particularly in terms of its extensibility, and that was driven almost entirely by issues and pull requests opened by members of the community.

What has the community reaction been like to Spring REST Docs?

I've been really pleased with the reaction thus far. The benefits that REST Docs offers really seem to click with people. Some have complained about the extra effort that's required, including the need to write tests for your service, but once they've seen the improved accuracy and usability of the documentation they're almost always sold on the idea. Members of the community who have enjoyed the benefits of Spring REST Docs have also been keen to help others reap those same benefits via blog posts and conference presentations.

Do you have any examples of what you would consider good REST API documentation?

I really like GitHub's API documentation, particularly its structure and use of examples. It begins with an overview that describes things that apply to the API as a whole such as the use of HTTP verbs, hypermedia and rate limiting. It then moves on to documenting the API's resources. There are individual sections for each of the high-level concepts that you'd expect to find when thinking about GitHub, such as issues and pull requests. The individual sections are then broken down in terms of something a user may be trying to do, such as creating an issue. URIs are completely absent until you're looking at the documentation for performing a specific action using a specific resource. From what I've seen, this documentation structure really helps users to find what they're looking for quickly and easily.

I'm also a fan of pretty much any documentation that's been produced using Slate such as Travis CI and Stripe, Slate provides a template that encourages good documentation structure, while also providing an attractive HTML-based interface for the documentation that makes it easy to include example requests and responses, curl commands, and the like.

Do you have any future plans for Spring REST Docs?

Spring REST Docs 1.0 can only be used to document a service that can be tested with Spring MVC's Test framework. I'd like to remove that restriction. To that end work has begun on also supporting REST Assured. In this context, the key benefit of REST Assured over Spring MVC's Test framework is that REST Assured operates at the HTTP layer. This will allow Spring REST Docs to be used to document any HTTP-based API; they needn't be written in Spring or even be running on the JVM. As long as it's accessible via HTTP, Spring REST Docs will be able to document it.

I'd also like to improve the integration with Slate. Thus far, Spring REST Docs has focussed on using Asciidoctor, but Slate uses Markdown. Thanks to the community-driven extensibility improvements that went into 1.0, you can already configure Spring REST Docs to produce Markdown but it requires a little more effort than I would like. I'd like 1.1 to streamline things to make using Slate as easy as possible.

Last but not least, I'd like to explore making more use of Asciidoctor's extensibility. As I said above, I really like Slate, but it's "just" a very nice HTML template for API documentation. Some custom CSS for Asciidoctor's existing HTML 5 backend or, perhaps, a custom API documentation-specific backend could further streamline the experience for documentation authors.