A really good conversation about REST docs started over on twitter, but I’d like to continue it here where we have more room. Here’s the storify:
And here are my initial thoughts:
Andy’s solution is brilliant if you need to keep your docs in synch with your code and if your code is your single source of truth for your (REST) APIs and how they work. I’ve worked with it, and I love it. It’s utterly awesome for keeping writers and programmers (literally) on the same page.
But if you’re starting with design – with your API definition in, say, Swagger – and if that definition is your single source of truth, then you probably need not just a different doc solution, but a different way of thinking about how doc is related to the API design.
Specifically: if you generate a spec/definition from your code and validate it against the initial spec (one ideal workflow, at least), then it might make more sense to keep your doc in synch with the API definition, starting with a tool like Swagger2Markup (yes, I’d prefer the asciidoc flavor :-)), and proceeding to flesh out the content from there.
That said, I’m just beginning with a new team that is planning/hoping to work with this doc-from-spec workflow, so I can’t speak to its success in the real world. I’ll keep y’all posted if you’re interested, though, and I’d love to read any feedback you might have about its potential utility, flaws or gotchas, or anything else.