You can create an account with apiary by using your Github account. I have already created an account. I can now sign in using my Github account. As soon as you login, you will get a sample API to get familiar with tool. We can use this as the starting point for documenting our API. I have customized it for my project. We need to change the polls to the name of our API. We can change the request json to our application needs. Let's link our apiary account with Github. We need to create a repo for our API documentation project. Now we can Authorize apiary. Let's link this project to Github. We can search the repo and connect it. Let's add a dummy file to make this work. Let's commit and start sync. If we reload this page, we can see that sync succeeded. Let's make a change on Github and see the changes on apiary.
We can add MSON markup. We can define a product object and it's attributes. We can commit these changes. We need to remove the white space to fix these errors. We can save and push these changes to Github. We can now see this checkin on github.
We can add a header for products resource. We are going to replace all the JSON to avoid duplication and use MSON. We can declare the attributes of the response. It returns an array of products. The product has an id. We get a syntax error. We can fix it by using an object declaration and providing all the attributes under the object.
We can get a specific product by providing it's id. We need to specify the input parameter. We also specify the response and the status code. We need to provide the attributes of the response. The product object has id as the primary key.
Instead of duplicating the attributes we can use MSON format and specify that the response will be an array of products. Here we can include the product as the response. A product can have many landing pages, we can specify it here.
We need to define the landing page object. We can now install the aglio tool to generate the API docs. Let's get all the files from github. We can now generate the API documentation. We can see the JSON body. We can get all products. We can create a new product. We can also generate a three column documentation which looks better. We can see all the endpoints, the request and response JSON. Members only access video. Forgot password feature.
References
Aglio
HTTP API Documentation with Blueprint
Using API Blueprint with MSON
