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 (5)

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
 
luckynkosi profile image
Nhlanhla Lucky Nkosi

Nice and simple walkthrough. Thank you.

Some comments may only be visible to logged-in visitors. Sign in to view all comments.