I’ve heard bits and pieces of the ways teams automate (or don’t automate) their API documentation. We’re looking to upgrade our current offering at Venmo, so I’m wondering what are some recommended flows? We want something more customizable than many of the plug-and-play API documentation offerings because we want it to be on-brand and more custom.
When I was at Amazon Web Services, we did some in-house transformations that were generated when the schema was generated from source. If you have access to the transformation scenarios or scripts, this could be a viable solution, but requires that you keep your content in XML or possibly JSON.
You might want to check out what Tom Johnson is doing with API docs: http://idratherbewriting.com/category/api-documentation/
I think he’s been experimenting with automated generation.
Internal developer docs
So I looked at Venmo’s docs …if y’all are describing your (REST) APIs in Swagger or API Blueprint or RAML or I/O docs or …, there’s tooling against the description JSON/YAML to produce docs that are as customizable as your willingness to play with front-end frameworks permits.
If you’re not starting with the description, then the tooling generates the description from the code (annotations, etc) and then you run a UI tool over the description. It’s a lot of heavy lifting, at least for Swagger which is the one I know the best (not all that well, just well enough to know it wasn’t right for our situation with REST at Symantec).
The upside for Swagger et al for Venmo is that the Swagger-UI (or analogous tooling) generates “interactive docs” – IOW, gives you your sandbox with embedded docs. How good the doc part is, of course, depends on how good the content is that you provide to the doc-specific annotations/spec fields. And it doesn’t replace sample code.
We’re using Java + Spring, and there’s a recent nice solution for static docs (with no server runtime dependency, a big issue with the standard Swagger tooling and I assume the others too) – spring-restdocs, which simply adds a documentation method to the Spring MockMVC tests, and automatically generates a reference stub for each endpoint, in asciidoc. The generated asciidoc is then imported into files that live next to the code, but that can contain everything else you might want (detailed descriptions of parameters, cURL, separate pages for HTTP response codes/messages, etc). It’s a very elegant solution that lets you generate the basics but integrate them into a complete doc set. But it is completely dependent on Spring, AND on asciidoctor. The latter is a bit of a pain for our docs team, but we’re trying to take it as a learning opportunity.
In a way, spring-restdocs imitates what you can do with docs for Python, if you integrate docstrings/doctests/rst files/Sphinx. But I’m still learning Python (mostly b/c of the fantastic doc support ;))
So … all of this is moot if you’re writing, say, Ruby. And the high level answer is (as always, right?), “it depends.”
Apologies if I’ve gone on too long here or if this isn’t the kind of response you’re looking for. If it helps at all, though, I’d recommend looking at apievangelist.com – Kin Lane is an amazing resource. For me, at least, his stuff has been an exercise in drinking from the firehose, but it gives you context for docs like nothing else I’ve found.
You might want to watch (again …) Jody and Arthur’s presentation about Salesforce’s workflow. Jody doesn’t say much, but they do talk a little bit about what they do – their schemas are in XML, and they have an XSLT to convert it to DITA for their CMS. There’s still manual work on top of that, but it’s some automation.