We've just started designing a new api and gone done the json-schema path which is particularly suitable since we're using json-rpc over websocket / http post.

We've just started designing a new api and gone done the json-schema path which is particularly suitable since we're using json-rpc over websocket / http post. Aside from that whatever tool you use, having markdown as the base source is really useful as you can then display it however you want while still quickly read it in a terminal.