13

私は nodejs + Express で REST API を開発しており、同時に README ファイルで API を文書化しており、それを自動化できるかどうか疑問に思っていました。例えば与えられた：

app.get('/path/to', dosomething);
app.post('/path/to/:somethingelse', scream);

これを自動生成してほしい

GET: /path/to dosomething
POST: /path/to/:somethingelse scream
4

4 に答える 4

6

近づくことができます。

「res」オブジェクトを見てください。アプリ オブジェクトへの参照があることがわかります。そのため、res.app._router.map には、http メソッド (get、post など) の一連の配列が含まれています。たとえば、GET 配列には、パスとコールバック プロパティがあります。path はルート URL を提供し、 callback はルート ハンドラの配列です。ここから関数名を取得できます。

そう...

ドキュメントをファイルに出力するためだけに使用される新しいルートを作成します。そのルート ハンドラで、res.app._router.map.GET、res.app._router.map.POST などを解析します。

理想的ではありませんが、実行可能です。

于 2012-09-05T23:58:16.500 に答える
6

これは 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
于 2012-09-22T13:29:52.930 に答える
5

これを行うためのモジュールも探していましたが、必要なことを行うモジュールが見つかりませんでした。そこで私は最近、このモジュールを作成して、Express および Mongoose ベースの API の API ドキュメントを自動生成しました。API 開発者とフロントエンド開発者もこれに満足しているので、多くの時間を節約できます。

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

于 2014-03-17T10:03:46.643 に答える
0

JSDoc最善の方法は、次のようなネイティブの 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 ドキュメントは次のとおりです。

会社のニーズに合わせてそのようなプラグインを作成しますが、おそらく会社固有のものになるため、今のところオープンソースにはなりません。しかし、実際に標準または抽象になる場合は、github プロジェクトをここにリンクします。

他の誰かがそのようなコンポーネントを知っているか開発している場合は、この回答のコメントにリンクを投稿してください;-)

于 2016-04-05T22:38:56.957 に答える