From past 5 years I have been working with lot of technical teams struggling to version APIs and create API documentation as per spec change. After boom of version control tools like Github & SVN teams are able to track source code but updating API specs for every minor change is still something that developers forget or don’t really care to update on time. It doesn’t matter much if nobody else is consuming their APIs but if APIs are exposed as REST- developer/app should know at same time that something was changed in API.
Teams are still able to track major API version releases but minor spec change in APIs are untracked most of the time, sometimes cause of communication gap and sometimes cause of improper documentation, leading to frustration within teams and products. As developers, how do we version our APIs without giving this responsibility to one more person who has to coordinate with each and every developer of team trying to figure out what was updated and manually updating documentation at end of the day?
Recently, I came across a tool that made my life as a product developer plain sailing. Now the developer who is working on server side API needs to add comments in his code in proper format and anyone from team will be able to generate API document out of it. Whenever server team works on any functionality they update comments in their own code giving it a minor release number if required and team will be able to generate documentation if they have access to latest updated server code without knowing server code language on my local. Take below example for instance
/**
* @api {POST} /route/api/ Login
* @apiName Login
* @apiGroup Authentication
*
* @apiParam {Username} Username
* @apiParam {Password} Password
*
* @apiParamExample {json} Request-Example:
*{
* "Username": "test",
* "Password": "Test123",
*}
* @apiSuccessExample Success-Response:
*{
* "Code": 1,
* "Message": "Signed in Successfully",
*}
*
* @apiError User Id/Password Is Incorrect.
*
* @apiErrorExample Error-Response:
*{
* "Code": 1,
* "Message": "User Id password is incorrect",
*}
*/
/**
* @api {POST} /route/api/ Signup
* @apiName Signup
* @apiGroup Authentication
*
* @apiParam {Username} Username
* @apiParam {Password} Password
* @apiParam {Email} Email
* @apiParam {FirstName} FirstName
* @apiParam {LastName} LastName
*
* @apiParamExample {json} Request-Example:
*{
* "Username": "test",
* "Password": "Password",
* "Email": "Email",
* "FirstName": "FirstName",
* "LastName": "test",
*}
* @apiSuccessExample Success-Response:
*{
* "Code": 1,
* "Message": "Signed up Successfully",
*}
*
* @apiError User Id/Password Is Incorrect.
*
* @apiErrorExample Error-Response:
*{
* "Code": 1,
* "Message": "Please check details again",
*}
*/
The above code in your own JavaScript/C#/PHP will generate an API documentation for you with an awesome left menu and standard parallax style API documentation.
Install apidoc using npm
npm install apidoc -g
Create apidoctemplate directory in root of your project
apidoc -i js/ -o apidoc/ -t mytemplate/
Create apidoc.json
vi apidoc.json
Configure your apidoc.json
{
"name": "My REST API documentation",
"version": "0.1.0",
"description": "My REST API documentation",
"title": "Detailed REST API documentation",
"url" : "https://yourdomain.com"
}
Run apidoc
apidoc
You can find your documentation here.
/doc/index.html
Now each time your server-side developer friend updates any spec ask him to edit the comment in code and your updated REST API documentation is ready.
