如何从Expresspath映射中自动生成API文档？
我在nodejs + Express中开发了一个REST API，并且在README文件中同时logging了我的API，我想知道是否可以自动化它。 例如给出：
app.get('/path/to', dosomething); app.post('/path/to/:somethingelse', scream); 我希望它自动生成这个
GET: /path/to dosomething POST: /path/to/:somethingelse scream
这是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
你可以closures。
看看“res”对象。 你会看到它有一个对你的应用程序对象的引用。 所以，res.app._router.map包含一组http方法（get，post等）的数组。 说在GET数组中，有一个path和一个callback属性。 path会给你路由的URL，callback是一个路由处理程序的数组。 从这里你可以得到函数名称。
所以…
制作一个纯粹用于将doco输出到文件的新路线。 在该路由处理程序中，parsingres.app._router.map.GET，res.app._router.map.POST等。
不理想，但可行。
我也在寻找一个模块来做到这一点，但我找不到我所需要的。 所以我最近创build了这个模块来为基于Express和Mongoose的API自动生成API文档。 这为API开发人员节省了大量时间，前端开发人员也对此感到满意。
我认为抓取路线来生成API文档是一个坏主意 。 自动生成的文档通常与JavaDoc一样：未被使用，被遗忘并最终被放弃。 最终的文档通常太简单，缺乏人性化的维度。
免责声明：我运行一个用于生成REST API文档的启动，它正好也build立在node.js + express 。 通常我会提到一个不做商业插头的问题，但是我认为这个问题太多了。 我们确保尽可能简单地维护API文档： http ： //apiary.io/ （如果您有兴趣，请ping我邀请）
我认为最好的方法是find或开发一个JSDoc插件来添加新的标签来parsing自定义的文档块，结合本地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文档。
我将为我的公司的需要创build一个这样的插件，但现在不会是开源，因为它可能是公司特定的。 但是，如果实际上它将是标准的或抽象的，我将在这里链接github项目。
如果其他人知道或开发这样的组件，请张贴链接评论这个答案;-)