Ask HN: Best way to document RESTful APIs?
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.
I have use Swagger and it seems quite good.