Как автогенерировать документацию API из Экспресс-сопоставлений маршрутов?

Я разрабатываю 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
11
express literate-programming node.js rest self-documenting-code

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
3

вы можете сблизиться.

посмотрите в объекте "res". Вы увидите, что он имеет ссылку на объект приложения. Итак, рез.app._маршрутизатор.карта содержит набор массивов для http-методов (get, post и т. д.). Скажем, в массиве GET есть путь и свойство обратного вызова. path даст вам url-адрес маршрута, а обратный вызов-это массив обработчиков маршрутов. Отсюда вы можете получить имена функций.

Так...

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

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

5

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

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

4

Я думаю, что маршруты очистки для создания документации API-это плохая идея. Автогенерированная документация обычно идет так же, как JavaDoc: неиспользуемая, забытая и в конечном итоге заброшенная. Полученная документация, как правило, слишком проста и лишена человеческого измерения.

предупреждение: Я запускаю запуск для создания документации REST API, которая, как это происходит, также построена на node.js+express. Обычно я стараюсь не делать рекламу. но я думаю, что это слишком много и актуально. Мы делаем поддержание документации API максимально простым:http://apiary.io/ (пинг меня для приглашения, если вы заинтересованы)

1

Я думаю, лучший способ-найти или разработать JSDoc плагин для добавления новых тегов для разбора настраиваемых блоков документации в сочетании с собственными тегами jsdoc, такими как folowing :

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 здесь.

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

0