HN Explorer

Ask HN: Best way to document RESTful APIs?

2 points by alexk307 ↗ HN
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?

2 comments

[ 23.4 ms ] story [ 219 ms ] thread
dozzie
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.
sidcool
I have use Swagger and it seems quite good.