JSDocからAPIのドキュメントページを生成してくれるapidocがいい感じ

Node.jsでRESTful APIを実装したサービスを作るとき、意外と面倒なのがAPIドキュメントの整備です。
自分で使うだけなら「ソース嫁」でいいわけですが、他人にも使ってもらうには見やすく情報を表示することが必要です。とはいえ手間はかけたくないわけで、以前はDoccoなどを紹介しました。

今回はAPIドキュメントの記述に特化したapidocを使ってみます。

apidoc

インストールはNPMからさくっと行えます。

> npm install -g apidoc

基本的な使い方は以下のような感じ

> apidoc -i [input file directory] -o [output file directory] -t [template file directory] -f [input file filter (default *.js)]

オプションを省略すると、カレントディレクトリ以下の *.js ファイルを探して、 doc/ ディレクトリに吐き出すようです。

APIドキュメントの記述についてはapidocのExampleを、出力イメージはapidocのOutput Exampleを見てください。

シンタックスを覚えるのが若干大変ですが、レスポンス構造の継承などができるので、大きなWebAPIのドキュメンテーションには役立ちそうです。

素敵ですね：）