Generating Markdown documentation for nodejs REST API

Hello! In this post I'll describe my quick and dirty solution for documenting node.js REST API. When I started exploring possible ways of documentation, I found two approaches:

  • Documentation in code
  • Separate documentation

For my OSS projects it's a overkill to create a separate site with documentation, so I decided to do everything just in code. Short description of my project: it's simple node.js server providing REST API for the clients.

Javascript have a lot of libraries for generating documentation via code, mainly all of them were forks of Java librarires or were based on jsdoc. These tools are good for documenting code, but absolutely bad for documenting REST API calls.

For documenting REST API calls I found excellent tool called ApiDoc, it's provides you with a building blocks for documenting REST API's.

/**
 * @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.
 */

Just add special comments for each method of your REST API and run ApiDoc on your source files.

apidoc -i src/api -o doc/  

As a result, you'll get fully functional static html documentation. Check the screenshot below.

Html documentation

But I'm lazy enough to create separate site for documentation, and I would like to post my docs as markdown formatted file on GitHub. No problem, there is a way. Project apidoc-markdown can convert generated by ApiDoc static html to single markdown file.

apidoc-markdown -p doc/ -o API_DOC.md  

The result file can be uploaded to GitHub.

Markdown documentation

To generate your documentation file just by one command npm docs add "docs": "apidoc -i src/api -o doc/ && apidoc-markdown -p doc/ -o API_DOC.md" to your package.json file.

That's it!