如何从Express路由映射中自动生成API文档？

Question

我正在开发nodejs + Express中的REST API,我一直在README文件中记录我的API,我想知道是否可以自动化它.例如:

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

我想让它自动生成这个

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

Answer 1

这是 javascript，您可以轻松地修补原始方法以生成文档。

以下是 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)

您还可以使用handler.toString(). 添加一些 Regex-Fu，您可以从这样编写的函数中提取更多注释：

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

Answer 2

你可以近距离接触.

看看'res'对象.您将看到它具有对您的app对象的引用.因此,res.app._router.map包含一组http方法的数组(get,post等).比如在GET数组中,有一个路径和一个回调属性.path将为您提供路由url,而callback是一个路由处理程序数组.从这里你可以得到函数名称.

所以...

制作一条纯粹用于将doco输出到文件的新路线.在该路由处理程序中,通过res.app._router.map.GET,res.app._router.map.POST等解析.

不理想,但可行.

Answer 3

我也在寻找一个模块来做到这一点，但我找不到一个可以完成我需要的模块。所以我最近创建了这个模块来为基于 Express 和 Mongoose 的 API 自动生成 API 文档。作为 API 开发人员，它为我节省了大量时间，前端开发人员也对此感到满意。

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