Generating API docs with Apiary.io #TIL
Apiary.io is a neat service that helps you create mock APIs. It also provides an editor to document and publish your APIs. While the latter is trivial to do on your own; using apiary.io gives you some useful features. For example, it gives you a neat interface to test against a mock or production API. This lets you read the test as you read the docs. Apiary.com hosts the mock server and returns dummy data from your documentation.
Check out the greppage api documentation to get an idea.
To publish your docs successfully they have to adhere to a standard. The standard requires you to write the documentation in a Markdown like format. Only difference is here is that there are more rules. Spacing is important! I’m not a terrible fan of the standard but once you get used to it, it’s not too bad.
Overall I like the product and it is great to quickly publish your API. The product also helps teams by decoupling the timelines of front-end and back-end. The front-end folks can test off the Mock server until the back-end folks finish work on the API. Really useful for hackathons if your team is split that way.