13

我正在 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
4

4 回答 4

6

你可以靠近。

查看“res”对象。您将看到它引用了您的应用程序对象。因此， res.app._router.map 包含一组用于 http 方法（get、post 等）的数组。比如说在 GET 数组中，有一个路径和一个回调属性。path 将为您提供路由 url，而 callback 是一个路由处理程序数组。从这里您可以获取函数名称。

所以...

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

不理想，但可行。

于 2012-09-05T23:58:16.500 回答
6

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

这是咖啡脚本中的示例代码：

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
于 2012-09-22T13:29:52.930 回答
5

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

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

于 2014-03-17T10:03:46.643 回答
0

我认为最好的方法是找到或开发一个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);
};

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

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

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

于 2016-04-05T22:38:56.957 回答