Posted at

PHPでのAPIドキュメント作成ツール(RESTful APIとソースコードドキュメント生成)

More than 3 years have passed since last update.

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のモックサーバを用意してくれるので、

さくっとテストしたい場合は便利。


参考