I recently revisited an old blog I wrote on technical documentation after running into a problem with some REST API documentation. In case you missed it, you can read the blog here. The process of resolving the issue – along with other experiences accumulated over the year – has me firmly convinced that several of the rules I postulated in the blog (points two through four to be precise) should be part of every development teams golden standard. I know they will be for mine.
The products I manage expose a very rich set of REST APIs. These services are consumed by many third party clients, as well as the UI layer of the application itself. A business need arose several months ago that necessitated a minor change to one of the API methods. The change was implemented, moved through QA without incident and then quickly pushed to production. Time was tight and the documentation was never updated to reflect the changes. New business pressures and priorities stole our focus and the minor API changes were soon forgotten.
Sound familiar?
C’mon, raise your hand. You can admit it. This scenario can be common in any fast, agile start-up or small shop.
Fast forward a few months when one of our clients incorporated that very same service into their own software. Of course, since the documentation didn’t match the new code, the service did not work as intended. They were puzzled and started to troubleshoot …
Then they called us. Our developer, who did not code the original change, was also puzzled and started to troubleshoot …
Does this also sound familiar?
In total, the combined teams burned approximately 10-12 man hours troubleshooting a non-issue caused by our own out-of-date documentation. That might not sound like a lot of time to some teams. However, when your team is relatively small and they work in an environment that moves exceedingly fast, every hour counts. If you have a big team, then the hours and costs can really add up.
I lamented about the issue in the following sprint retrospective. We use JavaDoc for internal automated source documentation, but it doesn’t really work for a REST API. The team spent some time searching for a documentation tool that would fit our needs, but they came up empty handed. [1]
Coincidentally, one of the developers on the team was experimenting with the ODF Toolkit. He heard my plea and showed off a prototype document generator a week or so later. I liked what I saw and turned his R&D experiments into a real project. A few days later I had a tool that can auto-generate REST service documentation from the source code at the touch of a button.
The tool is fairly slick. It uses a combination of Java Reflection and custom annotations to build documentation directly from the source code. In a nutshell, the tool looks for methods flagged with the custom annotations. When such a method is found, the annotations, the method signature, and the JavaDoc comments are parsed, compiled, and then passed along to the ODF Toolkit. The ODF Tookit is used to format the data into a nicely polished document and then export it to one of several common document formats. The following is a code snippet of a sample method and custom annotation to whet the appetite:
/**
* Gets configured stores.
*
* @param request the current http request
* @return the response
*/
@ResponseBody
@RequestMapping( value = "/appointment/stores", method = RequestMethod.GET )
//@formatter:off
@Generator(
title = "Get Stores",
description = "Gets configured stores.",
tokens = { "customer", "employee" },
returnTypes = StoresResponse.class
)
public StoresResponse getStores( final HttpServletRequest request )
{
. . .
}
@ResponseBody and @RequestMapping are Spring Annotations. @Generator is a custom annotation that feeds specific text to the document generator. The resultant documentation looks like the following:
Admittedly, for the tool to be effective, developers need to spend a few extra minutes to add the custom annotations while they code. We’ve found that the additional effort is not significant, particularly for those used to writing JavaDoc statements as they code. The resultant payoff, however, is enormous: effortless and 100% accurate document creation.
Furthermore, I now have a fairly extensible tool I can use to meet other documentation needs. For instance, I recently required a list of all the application’s exposed resources. With very little effort, the generator was extended with an option to automatically create a list of all URIs. Since the list is generated from the source, it is always correct and that custom page built five years ago for the client that cancelled two years ago won’t be missed. The resultant list included the URI, HTTP action used to access the URI, any headers the resource accepted along with the role required to access the resource. Nice and tight.
Ultimately, the ability to easily and automatically generate accurate REST API documentation has saved time and significantly reduced API client error rate which equals money saved in customer and dev support. The key is “easy”, and “automated”. To be effective, whatever tool you choose should adhere to the same concepts.
1. Ironically, I’ve found some interesting looking tools since then. http://miredot.com/, for example.