Я разрабатываю REST API в nodejs + Express, и я одновременно документировал свой API в файле README, и мне было интересно, можно ли его автоматизировать. например Дано:
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
Вы можете приблизиться.
Посмотрите на объект res. Вы увидите, что он имеет ссылку на ваш объект приложения. Таким образом, res.app._router.map содержит набор массивов для методов http (get, post и т.д.). Скажем в массиве GET, есть путь и свойство обратного вызова. path даст вам URL-адрес маршрута, а callback - это массив обработчиков маршрутов. Отсюда вы можете получить имена функций.
Итак...
Создайте новый маршрут, который используется исключительно для вывода вашего doco в файл. В этом обработчике маршрута проанализируйте файл res.app._router.map.GET, res.app._router.map.POST и т.д.
Не идеальный, но работоспособный.
Я также искал модуль для этого, но я не мог найти тот, который сделал то, что мне нужно. Поэтому я недавно создал этот модуль для автоматического создания API-документов для API на основе Express и Mongoose. Это экономит много времени, так как разработчик API и разработчики интерфейсов тоже довольны этим.
Я думаю, что очистка маршрутов для создания документации API - это плохая идея. Автогенерированная документация обычно идет так же, как JavaDoc: неиспользуемый, забытый и в конечном итоге заброшенный. Результирующая документация, как правило, слишком простая и не имеющая человеческого измерения.
Отказ от ответственности: Я запускаю запуск для создания документации REST API, которая, как это происходит, также построена на node.js + express. Обычно я делаю ставку на то, чтобы не делать коммерческие пробки, но я думаю, что это слишком много места и актуально. Мы действительно упрощаем ведение документации API: http://apiary.io/ (пинг меня для приглашения, если вам интересно)
Я думаю, что лучший способ - найти или разработать плагин JSDoc для добавления новых тегов для разбора настраиваемых блоков документации в сочетании с собственными тегами jsdoc, например, следующим образом:
NB: следующий пример не завершен, нет необходимости в избыточности, чтобы проиллюстрировать...
'use strict';
/**
* @file defines all server routes for the Article resource
* @name articles.server.routes.js
* @author Rémi Becheras <[email protected]>
*/
/**
* @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.
Я создам такой плагин для нужд моей компании, но сейчас он не будет openource только потому, что он, вероятно, будет специфичным для компании. Но если на самом деле это будет стандартным или абстрактным, я свяжу проект github здесь.
Если кто-то знает или разрабатывает такой компонент, пожалуйста, разместите ссылку в комментариях к этому ответу; -)