[kikibobo69]

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.