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

       

网上收集的解决方案 "如何从Expresspath映射中自动生成API文档?"

这是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开发人员节省了大量时间,前端开发人员也对此感到满意。

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

我认为抓取路线来生成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项目。

如果其他人知道或开发这样的组件,请张贴链接评论这个答案;-)