mson

I work at Apiary and we have a format called MSON for writing data structures in Markdown. https://github.com/apiaryio/mson/

Disclaimer: I work for Apiary. API Blueprint [1] is an open source API description format which can be used to intuitively describe an API. MSON [2] is a recent addition to the above format which makes it easy to describe all kinds of complex requests and responses in the spec. You can email me at pavan [at] apiary [dot] io if you have any more questions. [1]: http://apiblueprint.org [2]: http://github.com/apiaryio/mson

> Do you plan to write and update the JSON Schema by hand? Currently, yes, unfortunately. ;____; We've talked about doing it in an intermediate format, like YAML, which is slightly less painful, but....ugh. Years ago I wrote a very badly-coded-but-essentially-functional tool called Panino, which converted Markdown-to-JSON: https://github.com/gjtorikian/panino-docs/tree/master/lib/pa.... I see that some people have picked up on that and ran along with it, too: https://github.com/apiaryio/mson. So there might be something there to explore. 2. I've never looked into either. I know Swagger is used by several companies, like Twitter, but API Doc is new to me.