我正在 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
【问题讨论】：
标签： node.js rest express literate-programming self-documenting-code
这是 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
【讨论】：
.toString() 时，它们会出现。小心使用 minifiers 或 coffeescript 编译器。
你可以靠近。
查看“res”对象。您将看到它引用了您的应用程序对象。 因此， res.app._router.map 包含一组用于 http 方法（get、post 等）的数组。 比如说在 GET 数组中，有一个路径和一个回调属性。 path 将为您提供路由 url，而 callback 是一个路由处理程序数组。从这里您可以获取函数名称。
所以...
创建一个纯粹用于将你的 doco 输出到文件的新路由。在该路由处理程序中，解析 res.app._router.map.GET、res.app._router.map.POST 等。
不理想，但可行。
【讨论】：
我也在寻找一个模块来执行此操作，但我找不到可以满足我需要的模块。所以我最近创建了这个模块来为基于 Express 和 Mongoose 的 API 自动生成 API 文档。作为 API 开发人员，它为我节省了很多时间，前端开发人员对此也很满意。
【讨论】：
我认为最好的方法是找到或开发一个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 项目。
如果其他人知道或开发了此类组件，请在此答案的 cmets 中发布链接；-)
【讨论】：