如何从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

- pathikrit

Answer 1

你可以接近实现目标。

查看'res'对象。你会发现它引用了你的应用对象。 因此，res.app._router.map包含一组数组，用于http方法（get、post等）。 假设在GET数组中，有一个路径和一个回调属性。路径将给出路由url，回调是路由处理程序的数组。从这里，你可以获取函数名称。

所以...

创建一个新路由，仅用于将你的文档输出到文件中。在该路由处理程序中，解析res.app._router.map.GET、res.app._router.map.POST等。

不是最理想的方法，但可行。

- Phil Caithness

Answer 2

这是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()来获取处理程序函数的代码。再加上一些正则表达式技巧，您可以从这样编写的函数中提取更多的注释：

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

- zah

---

实际上，您不需要使用字面量来表示注释。您可以使用注释。当您使用.toString()时，它们会显示出来。请注意缩小器或咖啡脚本编译器。 - Diogo Gomes

Answer 3

我也曾寻找一个模块来完成这个任务，但我找不到一个满足我的需求的模块。因此，我最近创建了这个模块，用于自动生成基于Express和Mongoose的API文档。作为API开发人员，它为我节省了很多时间，而前端开发人员也很喜欢它。您可以在以下链接中找到这个模块：https://www.npmjs.org/package/express-mongoose-docs。

- nabeel

---

无法与Express 4一起工作（可能是因为app.routes不再存在） - rahul

安全警告：他在JavaScript中放置了分析工具。搜索“Mixpanel”。作者没有提及。 - JP_

Answer 4

我认为最好的方法是找到或开发一个 JSDoc 插件，以解析自定义文档块并添加新标签，与原生的 jsdoc 标签结合使用，例如下面的示例：

NB：以下示例不完整，没有必要重复说明...

'use strict';

/**
 * @file defines all server routes for the Article resource
 * @name articles.server.routes.js
 * @author Rémi Becheras <[e-mail]>
 */

/**
 * @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);
};

这是关于jsdoc插件的JSDoc文档在这里。

我将为我们公司的需求创建一个这样的插件，但目前它不会开源，因为它可能是公司特定的。但如果它实际上是标准或抽象的，我会在这里链接github项目。

如果有其他人知道或开发了这样的组件，请在此答案的评论中发布链接;-)

- Rémi Becheras

---

你有没有遇到过任何针对这个的jsdoc插件？ - tomalex

不，还没有，但我想我会在接下来的30天内开发这样的插件。这是我创建的存储库，用于托管项目：https://github.com/sirap-group/jsdoc-plugin-connect - Rémi Becheras

是的，确实如此，但它可以激发文档路线的灵感。 - Rémi Becheras