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

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 2

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