What is the best way to document a RESTful API? I've used tools like Swagger/Apiary before, but they require a considerable amount of manual work when writing all the specs. Is there a better more automated approach to this that you have used?
You see, the problem you're facing comes from the fact that REST is not
a protocol, but a pattern, so when you need to document external interface,
you need to document not only what functions you have, but also how does the
protocol look like. Proper RPC protocols (e.g. JSON-RPC) give much less work.