Как автоматически сгенерировать документацию API из картографических маршрутов Express?

Я разрабатываю 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
Источник

5 ответов

Решение

Это 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-адрес маршрута, а обратный вызов - это массив обработчиков маршрута. Отсюда вы можете получить имена функций.

Так...

Создайте новый маршрут, который используется исключительно для вывода вашего документа в файл. В этом обработчике маршрута выполните синтаксический анализ res.app._router.map.GET, res.app._router.map.POST и т. Д.

Не идеально, но выполнимо.

Источник

Я также искал модуль, чтобы сделать это, но я не мог найти тот, который сделал то, что мне было нужно. Поэтому недавно я создал этот модуль для автоматической генерации документов API для API Express и Mongoose. Это экономит мне много времени, так как разработчик API и разработчики интерфейса также довольны этим.

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

Источник

Я думаю, что очистка маршрутов для генерации документации 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 <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.

Если кто-то еще знает или разрабатывает такой компонент, пожалуйста, оставьте ссылку в комментариях к этому ответу;-)

Источник
Другие вопросы по тегам