Tightly coupling your (REST) API docs

Accepted Session
Short Form
Scheduled: Wednesday, June 22, 2016 from 2:30 – 3:15pm in B201


Documenting REST APIs isn't easy, and we need practical tips and tricks for keeping docs in sync with design and implementation. This talk explores some different but related ways to accomplish the goals of user-friendly, always up-to-date API docs.


There’s a lot of discussion lately on the interwebs about what good API documentation should include. There’s a lot less discussion about how to make those good API docs happen. The problem — and it is a problem, for the case of the REST APIs that are typically what folks mean by “API” these days — is that REST is not a specification or a standard. It is, as Fielding explicitly stated in his 2000 dissertation that gave the critters their name, an architectural style.

Which means that there’s no standard tooling for documenting REST APIs. There’s no Javadoc tool, or doxygen, or .NET comments/tooling, nor do standard code comment/documentation from comments tools for other languages serve the purpose well by default either. Yes, there are REST doclets for the Javadoc tool, and various customizations of the generated-from-comment systems of other languages, but none of them (almost!) addresses the problem adequately.

And for good reason. There are nearly as many ways to describe and implement a REST API as there are programmers assigned the task of doing the work. Some conventions have appeared over the years, and some seem to be moving to the forefront (notably Swagger, as a description specification, although RAML and API Blueprint have their following as well).

So what’s a responsible documentarian to do?

First, stop documenting manually. You need to automate as much as you can to make sure that your docs stay in sync with your design and with your implementation. Ideally, automate reference doc stubs from your design (API description) AND automate sample calls (at a minimum) from your tests. But you also cannot and must not give up human intervention, to explain and illustrate.

This talk would discuss specific toolsets (with options) as well as work still to be done to provide this kind of functionality. Swagger2Markup is one tool that lets you export content stubs for a REST API that’s been described according to the Swagger specification to either Markdown or AsciiDoc files. These files can then be manually edited to provide more detailed descriptions of resources, operations, and properties, and then be converted to standard HTML markup for serving on web pages.

There are also tools for generating samples and more detailed documentation from tests, such as spring-restdocs (if, of course, you’re already using the Spring framework). I’d talk about other options, too, notably Python’s docstrings and doctests, which have been nicely leveraged for Django-based REST frameworks and others.

The point would not be to recommend specific tools, but to use these and other examples to illustrate how to keep your REST API docs in sync with your design and implementation, without sacrificing the much-needed human element that fleshes out all the automated pieces and knits them together into a coherent whole that your users can find helpful and even compelling.

Speaking experience

DC API Meetup, April 2016: "Documenting Your API: Options and challenges"
APIStrat 2015, Austin TX: "Your API Needs Technical Writers"
Write the Docs EU 2015, Prague, CZ: "Back to the Future: Tales from the history of software documentation" (yes the proposed talk builds on this talk)
Dev-to-Dev Summit, February 2015, SF: "Documenting REST APIs" (with Jason Wiener)
Write the Docs PDX Meetup, November 2014: Documenting REST APIs (with Jody Bleyle, Salesforce)


Leave a private comment to organizers about this proposal