DEV Community

Cover image for How to document a nodejs api with apidoc
Siqueira
Siqueira

Posted on

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.

Alt text

How can i use ?

First of all you need to configuring the environment:

  "npm install apidoc -g"
Enter fullscreen mode Exit fullscreen mode

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/"
   }
 }
Enter fullscreen mode Exit fullscreen mode
  • 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"
 }
Enter fullscreen mode Exit fullscreen mode

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)

Enter fullscreen mode Exit fullscreen mode

Top comments (6)

Collapse
 
luckynkosi profile image
Nhlanhla Lucky Nkosi

Nice and simple walkthrough. Thank you.

Collapse
 
wakeupmh profile image
Marcos Henrique

Great post dude 🀩

Collapse
 
themsiqueira profile image
Siqueira

Thanks man! ✌😁

Collapse
 
matheusgomes062 profile image
Matheus Gomes πŸ‘¨β€πŸ’»

I think it's awesome to have such package, i never imagined we could do such a thing. Thanks for sharing! 😎

Collapse
 
wijaaa profile image
wijaaa

thanks for your post I do this steps but I get an error that I cannot solve it maybe you can help me

Collapse
 
themsiqueira profile image
Siqueira

Hey, sorry for delay, how can i help you?