How to autogenerate API documentation from Express route mappings?

Question

I am developing a REST API in nodejs + Express and I have been simultaneously documenting my API in the README file and I was wondering if it is possible to automate it. e.g. given:

app.get('/path/to', dosomething);
app.post('/path/to/:somethingelse', scream);

I want it to auto generate this

GET: /path/to dosomething
POST: /path/to/:somethingelse scream

Answer 1

This is javascript, you can easily patch the original methods to also generate the docs.

Here is a sample code in coffeescript:

express = require 'express'
methods = require 'express/node_modules/methods' # array of all HTTP methods

app = express()

methods.forEach (method) ->
  orig = app[method]
  app[method] = (path, handler) ->
    console.log "patched method ", method, " ", path
    # generate docs here
    orig.apply(this, arguments)

You can also get the code of the handler function using handler.toString(). Add some Regex-Fu and you can extract more notes from a function written like this:

app.get "/foo", (req, res) ->
  "Lorem ipsum dolor sit amet, consectetuer adipiscing elit"
  more code here

Answer 2

You can get close.

Have a look in the 'res' object. You will see that it has a reference to your app object. So, res.app._router.map contains a set of arrays for the http methods (get, post, etc). Say in the GET array, there is a path and a callback property. path will give you the route url, and callback is an array of route handlers. From here you can get the function names.

So...

Make a new route that is used purely for outputting your doco to a file. In that route handler, parse though res.app._router.map.GET, res.app._router.map.POST etc.

Not ideal, but workable.

Answer 3

I was also looking for a module to do this but I couldn't find one that did what I needed. So I recently created this module to auto-generate API docs for Express and Mongoose based APIs. It saves me a lot of time as API developer and the front-end developers are also happy with this.

https://www.npmjs.org/package/express-mongoose-docs

Answer 4

I think the best way is to find or develop a JSDoc plugin to add new tags to parse customized documentation blocks, combined with native jsdoc tags, like the folowing :

NB: the following example is not complete, no need of redundancy to illustrate...

'use strict';

/**
 * @file defines all server routes for the Article resource
 * @name articles.server.routes.js
 * @author Rémi Becheras <[email protected]>
 */

/**
 * @namespace articles.server.routes
 */

/**
 * @module articles/server/routes
 */


/**
 * Article policy object
 * @var {Policy}
 * @inner
 */
var articlesPolicy = __.require('articles.server.policy');

/**
 * Article controller
 * @var {Controller}
 * @inner
 */
var articles = __.require('articles.server.controller');

// NB: `__.require()` is a project-specific method working as an helper for the native `require()` method, `__` is an object binded to the global context

/**
 * Exports a function that defines all routes of the `articles` module, binding it to the express `app` instance.
 * @function
 * @param {object} app The express application instance
 * @return void
 */
module.exports = function (app) {
  /**
   * Articles REST API resource end-point
   * @endpoint /api/articles
   * @name apiArticles
   * @version v1
   * @since v1
   * @description Articles REST API resource end-point
   */
  app.route('/api/articles').all(articlesPolicy.isAllowed)
    .get(articles.list)
    /**
     * Create a new article
     * @route
     * @verb POST
     * @name postArticle
     * @description If the user is logged in and has the 'author' role, it can create an article w
     * @example
      POST http://example.com/api/articles \
      --data { title: "my title", body: "<h1>my content</h1>" }
     */
    .post(articles.create);

  // Single article routes
  app.route('/api/articles/:articleId').all(articlesPolicy.isAllowed)
    .get(articles.read)
    .put(articles.update)
    .delete(articles.delete);

  // Finish by binding the article middleware
  app.param('articleId', articles.articleByID);
};

Here is the JSDoc documentation about jsdoc plugins.

I will create a such plugin for the needs of my company but it wont be opensource for now just because it will probably be company-specific. But if in fact it will be standard or abstract, I will link the github project here.

If someone else known or develop a such component, please post a link in comments of this answer ;-)