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
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.
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
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.
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 <rbecheras@sirap.fr>
*/
/**
* @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 ;-)
