PHPでのAPIドキュメント作成ツール（RESTful APIとソースコードドキュメント生成）
restfulなAPIのドキュメントを残す必要があったので、記載しておきます。
npmのapidoc http://apidocjs.com/
コメントにささっと書いてすぐ確認、バージョンの比較まで可能
インストール
npm install apidoc -g
プロジェクトルートにapidoc.jsonを用意して
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
ドキュメント生成
apidoc -i path/to/dir -f ".*\\.php$" -o path/to/output/dir -t template/path/
デモ
http://apidocjs.com/example/
以下のような記述で生成可能
/**
* @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) {
// dummy
return "ユーザー情報";
}
apigen http://www.apigen.org/
ソースコードドキュメントであればこちらを採用
見やすくシンプル Bootstrapのテーマも使用可能
wget http://apigen.org/apigen.phar
chmod +x apigen.phar
mv apigen.phar /usr/local/bin/apigen
apigen --version
# get help for generate command
apigen generate --help
fuelPHPの場合
bin/apidoc.sh
#生成
apidoc -i fuel/app -f ".*\\.php$" -o public/apidoc/
その他
Apiary
ドキュメントの生成と同時にAPIのモックサーバを用意してくれるので、
さくっとテストしたい場合は便利。