How to document a nodejs api with apidoc

What is "apidoc" ?

Apidoc is a package to create documentation for api from notes in your source code.

Where can i use it?

The service is compatible with any programming language that allow block documentation.

How can i use ?

First of all you need to configuring the environment:

• install node from the link "https://nodejs.org/en/"

• install apidoc by command line below:
  

  "npm install apidoc -g"

Now we can start configure the project:

• install grunt-apidoc "npm install grunt-apidoc --save-dev"

Grunt is a task generator to apidoc

• On your root of your project you need to create a "Grunfile.js"

  • In your Gruntfile you need to add the options below to config the destination path to apidoc:

 apidoc: {
   myapp: {
     src: "app/",
     dest: "apidoc/"
   }
 }

• After that you need to create a file called "apidoc.json" to include information about your project:

 {
   "name": "example",
   "version": "0.1.0",
   "description": "apiDoc basic example",
   "title": "Custom apiDoc browser title",
   "url" : "https://api.github.com/v1"
 }

Obs:. this file is optional, it is just to describe your project, and you can add this config in your package json if it's a node project, but I preffer a separated file.

Now we can start making documentation.

To start you just need to comment before your endpoint like below:

/**
 * @api {get} /user/:id Request User information
 * @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": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

Let's generate the documentation with the command bellow:

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

We need to pass in the command three arguments, first the folder where we can search the comments, second the output and in the end if we make a template the path to template, the final result is the image below:

This is my first post on dev.to, I hope it was of any help, any questions or suggestions just comment below!