Generate human readable REST API document in NodeJs using an apidoc node module

Node.js is one of the top preferences of programming languages In cloud native application development. Many micro services provide functionality by exposing REST APIs. It's important for developers of consuming applications as well as the provider application to be able to read the definition and capabilities of each and every REST endpoint. The apidoc node module comes handy, this module helps application developers define and document the REST APIs with very less effort.

What is apidoc?

apidoc is a node plugin that can be installed in the node application. This plugin helps to write and generate REST API documents for node.js applications.

How to generate API documents using apidoc ?

First we need to install apidoc in the node.js project. Then we can use the @ parameters and formats as comments in the node.js files. After that we need to run a command to create the documentation. Apidoc scans all .js files in the path. It creates a nice human readable HTML static file from the comments in the .js files. The comments can be added in-place on top of each node route that provides the REST functionality.

A better approach though, is to separate the comments for documentation separate from code. We also can write all comments for all APIs in a separate .js file. Also, we can write a code snippet that will generate the documents automatically. Let’s see an example to understand it better.

The package.json file

{
  "name": "Test-App",
  "version": "1.0.0",
  "devDependencies": {
    "apidoc": "^0.25.0"
  },
  "apidoc": {
    "title": "Test-App API Documentation",
    "order": [
      "Users",
      "User"
    ]
  },
  "engines": {
    "node": "^12.18.0",
    "npm": "^6.14.4"
  }
}

In package.json we have mentioned the apidoc version under devDependencies. Note the app name and version, it will be used in the apidoc generated document. This file also has an apidoc element, here the title of the generated apidoc HTML file can be defined. The groups names and their order can also be defined here. Read along to know what groups are groups.

The .js file with apidoc comments

Here is a users.js file that contains all the comments. The file assumes creating a document for REST APIs for user management. It contains listing all users, creating and updating a user.

/**
 * @api {get} /users Get all users
 * @apiDescription Returns All user names.
 * @apiPermission None
 * @apiName GetUsers
 * @apiGroup Users
 *
 * @apiSuccess {Object[]} response Services metadata.
 * @apiSuccess {String} response.name user name.
 *
 * @apiSuccessExample {json} successful response(200 OK):
[
    {
        "name": "user name"
    }
]
 *
 * @apiError (Error 4XX) 404 Not Found.
 * @apiError (Error 5XX) 500 Internal Server Error.
 */

/**
 * @apiDefine ErrorCodes
 * @apiError (Error 4XX) 400 Bad Request.
 * @apiError (Error 4XX) 401 Unauthorized.
 * @apiError (Error 4XX) 403 Forbidden.
 * @apiError (Error 4XX) 404 Not Found.
 * @apiError (Error 5XX) 500 Internal Server Error.
 */

/**
 * @apiDefine UserRequestBody
 * @apiParam (Body/Json Parameter) {String} email Email of user.
 * @apiParam (Body/Json Parameter) {Number} age Age of user.
 * @apiParam (Body/Json Parameter) {String} name Name of user.
 * @apiParam (Body/Json Parameter) {String} [expdate] Optional membership expiry date.
 *
 * @apiParamExample {json} example request body:
 * {
 * "email":"[e-mail]",
 * "age":"1",
 * "name": "name",
 * }
 *
 * @apiSuccess {String} msg operation successful.
*/

/**
 * @api {post} /users Create user
 * @apiDescription create an user
 * @apiPermission Admin
 * @apiName CreateUser
 * @apiGroup User
 * @apiUse UserRequestBody
 * @apiSuccessExample {json} successful response(200 OK):
 * {"Msg":"Successfully created user with email: ***** "}
 * @apiUse ErrorCodes
 */

/**
 * @api {put} /users Update User
 * @apiDescription Update an user
 * @apiPermission Admin
 * @apiName UpdateUser
 * @apiGroup User
 * @apiUse UserRequestBody
 * @apiSuccessExample {json} Success-Response(200 OK):
 * {"Msg":"Successfully updated user with id: ***** "}
 * @apiUse ErrorCodes
 * @apiError (Error 4XX, 5XX) 400 Bad request.
 */

To read on the explanation of the tags read my blog generate human readable rest api document in nodejs using an apidoc node module

Now, I have written a code that can generate the documents automatically. The file name is genAPiDoc.js and its content is given below.

const apidoc = require('apidoc');
apidoc.createDoc({
  dest: "./webapp/apidoc",
  src: ["./apidoc_source"]
});

The source means the documents in commented form will be read from the apidoc_source folder and the docs will be generated under the webapp/apidoc folder.

The folder structure of our small project to generate api documentation I have depicted here

apidoc_source
  /users.js
node_modules
webapp
  /apidoc
genAPiDoc.js
package.json

At this point we have everything to generate the HTML document. To install all NPM modules we have to run the npm install command. Then we run the node genAPiDoc.js command to generate the human readable document. You will see lots of files and folders generated under the webapp/apidoc folder. Among them you will find the index.html. This is the file where we have the output of the document in a nice human readable format.

The screen shot of the html files generated are here

For the full view of the html page see my blog post