Create API Doc Using Node.Js

Node.js 

Node.js is a platform built on Chrome's Javascript runtime for easily building fast, scalable network applications. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient, perfect for data-intensive real-time applications that run across distributed devices.

Steps to create API Doc:

For creating API Doc using Node.js, we have to perform following steps:

1. Installing Node.js 
2. Installing Node packaged modules via npm 
3. Creating input files required to generate API Doc using Node.js 
4. Run commands to create API Docs

 

Installation of Node.js

Node.js has a Windows and Mac installer, as well as binaries for Linux users. Here I am describing installation process of Node.js for Windows but general process is same regardless of operating system or version you are using. 

To start over with node.js, first you have to download suitable Node.js installer and install it. For downloading installer, visit https://nodejs.org/download/. 

After downloading appropriate installer, install it on your computer by clicking on installer file to open Node.js Setup Wizard.

Just go through the Setup Wizard until Node has finished installing. 

Finally, we are done with node.js installation on our computer. After this installation, you have successfully installed node.js and npm (npm installed by default with node.js) .

Installation of Node packaged modules via npm

What is npm?

npm is a NodeJS package manager. As its name would imply, you can use it to install node programs. Also, if you use it in development, it makes it easier to specify and link dependencies. 

Node provides various packaged modules that you can install via npm. In this section, we will talk about apidoc module. 

We will install apidoc module and apidoc grunt-module in order to create documents. Here are npm commands to install above listed modules:

npm command to install apidoc module:

> npm install apidoc -g

npm command to install grunt-apidoc module:

> npm install grunt-apidoc --save-dev

Creating input files required to generate API Doc using Node.js

For creating document using node.js apidoc, we have generate following files:

1. apidoc.json
2. _apidoc.js
3. input file and it can be generated using any of following programming languages:
1. C#, Go, Dart, Java, JavaScript, PHP (all DocStyle capable languages)
2. CoffeeScript
3. Perl
4. Python and more

For more details, please read https://www.npmjs.com/package/apidoc

apidoc.json  - configuration file

The optional apidoc.json in your projects root dir includes common information about your project like title, short description, version and configuration options like header / footer settings or template specific options. 

{

"name": "write name of document",
"version": "0.2.0",
"description": "write your description about document",
"title": "write title of document",
"url" : "url to access document file",

}

_apidoc.js  - history file to maintain version

Nice feature is the keeping of previous defined documentation blocks. That makes it possible to compare a methods version with its predecessor. Frontend Developer can thus simply see what have changed and modify their code.
Before you change your documentation block in apidoc.json, copy the old block to to this file, that's all.

/*
 * This file contain old version documentation blocks.
 */

/**
 * @api {get} /user/:id Get User information
 * @apiVersion 0.1.0
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "Kalpana",
 *       "lastname": "Dixit"
 *     }
 *
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */ 

Input File (here i am creating using PHP)

/*
 * Versioning Example
 *
 * This is an versioning example for apiDoc.
 * Versioning keeps previous defined documentation blocks. That makes it possible to compare a methods version with its predecessor.
 *
 * Important is to set the version with "@apiVersion".
 *
 * Documentation blocks without @api (like this block) will be ignored.
 */

/**
 * @api {get} /user/:id Get User information and Date of Registration.
 * @apiVersion 0.2.0
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname  Firstname of the User.
 * @apiSuccess {String} lastname   Lastname of the User.
 * @apiSuccess {Date}   registered Date of Registration.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "Kalpana",
 *       "lastname": "Dixit"
 *     }
 *
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

For more details, please visit http://apidocjs.com/ 

Run commands to create API Docs 

After creating all input files, last step is to execute apidoc command for generating apiDoc document. 

Command for generating document: 

> apidoc -i myapp/ -o apidoc/ -t mytemplate/ 

Creates an apiDoc of all files within dir myapp/, uses template (if any) from dir mytemplate/ and put all output to dir apidoc/. 

Here -t template is optional if you don't have any template files. 

Without any parameter, apiDoc generate a documentation from all .cs .dart .erl .go .java .js .php .py .rb .ts files in current dir (incl. subdirs) and writes the output to ./apidoc/.

Congratulations! We have successfully generated document using node.js .

Check on your mentioned path for output, you will have index.html file inside apidoc (or folder name which you have specified for output) folder , open index.html file in browser and have a look at your api doc.