apibuilder

My former colleagues have been working on http://apidoc.me/ (https://github.com/gilt/apidoc). I really like this approach, which is basically: 1. specify the api in json 2. apidoc generates really nice api documentation 3. apidoc generates a single-file client for the service (currently ruby or scala) 4. apidoc generates a routes file for play2 It's scala-biased at the moment because that's their tech stack, but in practice an api-first approach seems to lead to higher quality APIs compared to just hacking something together and annotating it to extract docs. Also having a really nice client without a complicated compile-time dependency graph (on the JVM) feels like a sweet spot.

Thanks for comparison. I have not played with either your tool nor RTD yet, but I look forward to trying both. I came across the APIDoc project when watching an excellent presentation by the Gilt CTO titled "Immutable Infrastructure with Docker and EC2" [1]. It is worth a watch and he mentions that APIDoc allows them to more easily create new micro services in their cluster (of which they have over 300!). I was reading around the APIDoc site and saw they had a note to investigate Swagger 2.0 to see if it could be useful [2]. [1] https://www.youtube.com/watch?v=GaHzdqFithc [2] https://github.com/gilt/apidoc/blob/master/TODO#L95 I would love to see a few projects explore this concept of generating docs, client code, and server code from a single "ground truth" file and eventually have them all merge into a single defacto standard. That woul