How to autogenerate API documentation from Express route mappings?
Solution 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
Solution 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.
Solution 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
Related videos on Youtube
pathikrit
Experienced in developing scalable solutions for complex problems. I enjoy working full-stack - from architecting schema and data-flows, implementing algorithms, designing APIs to crafting innovative UIs. My professional interests include algorithms, functional programming, finance, data analytics and visualization.
Updated on June 25, 2022Comments
-
pathikrit about 2 years
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
-
Diogo Gomes over 11 yearsActually, 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. -
rahul almost 10 yearsNot working with Express 4 (probably app.routes doesn't exist anymore)
-
tomalex about 8 yearsDid you came across any jsdoc plugin for this?
-
Rémi Becheras about 8 yearsNo, 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
-
Rémi Becheras about 8 yearsYes indeed, but it can be an inspiration to documents routes
-
JP_ over 7 yearsSECURITY WARNING: He has put analytics in his JavaScript. Search for "Mixpanel". No mention by author.