この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
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