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

Horizon

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

Laud

Actually, you don't need to use literals for the notes. You can use comments. They show up when you use .toString(). Be careful with minifiers or the coffeescript compiler. – Derogate

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.

Fluky

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

Experimentation

Not working with Express 4 (probably app.routes doesn't exist anymore) – Return

SECURITY WARNING: He has put analytics in his JavaScript. Search for "Mixpanel". No mention by author. – Hackney

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 ;-)

Aurist

Did you came across any jsdoc plugin for this? – Bestir

No, not yet, but I think I'll develop a such plugin during the next 30 days. Here is the repository I created to host the project when I'll work on it : github.com/sirap-group/jsdoc-plugin-connect – Dandruff

Yes indeed, but it can be an inspiration to documents routes – Dandruff