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

你可以近距离接触。

查看'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 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()获取处理函数的代码。添加一些Regex-Fu，您可以从如下函数中提取更多注释：

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

Answer 3

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

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

Answer 4

我认为抓取生成API文档的路线是一个坏主意。自动生成的文档通常与JavaDoc的方式相同：未使用，遗忘并最终放弃。结果文档通常太基础，缺乏人性维度。

免责声明：我创建了一个用于生成REST API文档的初创公司，该文档也在node.js + express上构建。通常我会指出不做商业插头，但我认为这是太多的现场和局部。我们确实尽可能简化了API文档的维护：http://apiary.io/（如果您有兴趣请ping我邀请）

Answer 5

我认为最好的方法是找到或开发一个JSDoc插件来添加新标签来解析自定义文档块，并结合本机jsdoc标记，如下所示：

注意：以下示例不完整，不需要冗余来说明......

'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关于jsdoc插件的JSDoc文档。

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

如果其他人知道或开发此类组件，请在此答案的评论中发布链接; - ）

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

5 个答案: