ギロッポンよりこんにちは、ニタです。
今回はWebAPI向けのドキュメントジェネレーター「apiDoc」を紹介します。
ドキュメントジェネレーターといえば、ApiGenやDoxygen、phpDocumenterなどありますが、それらはクラス内メソッドについてのドキュメントであり、外部向けのドキュメントとしては不要な内容も記載されてしまいます。
RESTfulなAPIドキュメントとしてはちょっとドキュメントとしての意味合いが違います。
サンプルを見ていただくとわかると思いますが、apiDocは独自記法ではありますが、生成されたドキュメントの見易さとしては他のドキュメントジェネレーターより上だと思います。
※先日、弊社のサービス「extorage」のAPIが公開されましたが、そちらのドキュメントページの生成でも使用しています。
インストール
npmよりインストールしますので、予めインストールしておいてください。
まあ、node.jsと一緒にインストールされますので、node.jsをインストールすればいいでしょう。
mac以外は知りません。
brew install node npm install apidoc -g
ソースへの表記方法
javaDocとは違う独自記法をメソッドのアノテーションに表記します。
パラメータの説明はこちらにありますが、ざっと書くと以下のようになります。
/**
* メソッドへのリクエスト方法、URL、名前
* @api {get} /api/username username (ユーザー名)
* apiのバージョン
* @apiVersion 1.0.0
* apiの名前。生成されたページでのアンカー名になる。
* @apiName ユーザー名
* 所属するAPIグループ
* @apiGroup API
* 詳細説明。HTMLも表記可能。
* @apiDescription 現在ログイン中のアカウントユーザー名を返却します
*
* APIリクエスト時の返却内容のサンプル。ファイル形式がjsonの場合、以下のようにします。
* @apiSuccessExample Success-Response(example):
* HTTP/1.1 200 OK
* {
* "UserName" : ユーザー名,
* "message" : "OK",
* "response" : 200
* }
* エラー名。複数表記可能。
* @apiError NotFound 見つかりませんでした
* エラー時の返却内容サンプル。同じくjson形式で。
* @apiErrorExample Error-Response(example):
* HTTP/1.1 404 Not Found
* {
* "error" : "ファイルが見つかりません。",
* "message" : "Not Found",
* "response" : 404
* }
*/
public function username(){
// すばらしいコード
}
生成
実行コマンドは以下になります。
apidoc -i path/to/dir -f ".*\\.php$" -o path/to/output/dir -t template/path/
コマンドオプション
| -i | 対象のソースがあるディレクトリパス |
| -f | 上記-iで指定したディレクトリのどのファイルを対象とするか。1つのファイルだけの場合はファイル名を指定。デフォルトでjsファイルを対象とするので、上記のように拡張子指定も可能。 |
| -o | 生成したデータの出力先。 |
| -t | テンプレートディレクトリ。apidoc -hでデフォルトテンプレートのパスを参照可能。 |
実行すると、このようなページが生成されます。フラットデザインがイマドキ感があってシャレオツですね。
基本的にこれだけで生成可能ですが、APIのサービス名やバージョン、利用方法などの総合的な説明文などは、生成時に、別ファイルを読み込ませます。
※apidocの実行は、以下の2ファイルがあるディレクトリ上で行わないと読み込まれないようです。
| package.json | 生成するAPIのサービス名、説明文、バージョンなどを管理。 |
| API.md | 総合的な説明文。Markdown記法で表記。pakage.jsonにファイル名を追記して読み込ませる。 |
package.json
{
"name": "sample API",
"version": "1.0.0",
"description": "サンプルAPIのドキュメント",
"apidoc": "This is a description, it will be ignored if parameter apidocFilename exist.",
"apidocFilename": "API.md"
}
API.md
# ご利用にあたって ここに利用方法などの記載する。 ## 共通URL 各APIのエンドポイントのURLは以下を共通して使用します。 http://examp.le/sample/ ※ユーザー名取得の場合 http://examp.le/sample/api/username
また、テンプレートはbootstrapを使用しているので、カスタマイズも可能です。
