node.jsのいろいろなモジュール31 – apiDocでRESTful APIドキュメントを生成する

RESTアプリケーション用ドキュメント

apiDocモジュールは、RestfulAPI用ドキュメントジェネレーターです。
jsファイル内にJavadocやJsdocのように埋め込み、API用の説明を記述すると、apiDocコマンドでhtmlとして出力することができます。
デフォルトではこんな感じでドキュメントが出力されます。
なお、独自のテンプレートを使用することも可能みたいです。

環境構築方法

今回使用した動作環境は以下のとおりです。

• OS : MacOS X 10.7.5
• Node.js : v0.10.4
• npm : 1.2.18

npmを使用してモジュールをインストールしましょう。グローバルオプションをつけてapiDocをインストールします。

% npm install apidoc -g

これで問題なくapidocコマンドが使えるかと思ったのですが、私の環境だと、
「env: node＼r: No such file or directory」というメッセージがでてコマンドが使えませんでした。
そのうち修正されるとは思いますが、今回はgitでapiDocを取得し、apidocコマンドを指定しましょう。

% git clone https://github.com/apidoc/apidoc.git
%./apidoc/bin/apidoc -i /path/your/app/ -o /path/your/doc/  //　apiDoc実行

apiDocの使い方は簡単です。
jsファイルの関数に対して、ここにあるようなアノテーションを記述し、
どのようなURLがどのようなパラメータを使用してどのようなレスポンスを返すかを記述します。
試しにappディレクトリを作成し、そこにsamlpe.jsを下記のように記述しましょう。

/**
 * @api {post} /user/:id ユーザー取得
 * @apiVersion 0.1.0
 * @apiName ユーザー取得
 * @apiGroup User
 *
 * @apiParam {Number} id ユーザーのユニークID.
 *
 * @apiSuccess {String} firstname 名前.
 * @apiSuccess {String} lastname  苗字.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound ユーザーが見つからないとき.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */
function getUser(id) {
 //関数の中身は適当
 return "ユーザー情報";
}

REST情報を記述したjsファイルを作成したら、docディレクトリを作成し、apiDocコマンドで出力します。

% mkdir doc
% apidoc/bin/apidoc -i app/ -o doc/

出力が終わると、docディレクトリ以下にhtmlファイル群が生成されています。index.htmlを開いてみてください。
sample.jsで定義したREST情報が出力されています。

まとめ

簡単な記述でREST定義のドキュメントが生成できるので、なかなか役立つのではないでしょうか。
apiDocはいろいろなアノテーションを持っているので、確認してみてください。

参考サイトなど

• 公式: http://apidocjs.com/
• Github: https://github.com/apidoc/apidoc