DEV Community

Cover image for How to document a nodejs api with apidoc

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" : ""
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"
 *     }
Enter fullscreen mode Exit fullscreen mode

Let's generate the documentation with the command bellow:

"apidoc -i myapp/ -o apidoc/ -t mytemplate/"
Enter fullscreen mode Exit fullscreen mode

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

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

Alt Text

Top comments (5)

wakeupmh profile image
Marcos Henrique

Great post dude ๐Ÿคฉ

themsiqueira profile image

Thanks man! โœŒ๐Ÿ˜

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! ๐Ÿ˜Ž

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.