How to document a nodejs api with apidoc

#javascript #tutorial

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:

![Alt Text](https://thepracticaldev.s3.amazonaws.com/i/h4dbhol10xri3kac2nfh.JPG)

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

 ![Alt Text](https://media.giphy.com/media/3o6fJ1l3Wr1ugMu1Rm/giphy.gif)