【node.js】apiドキュメント作成ツールのapiDocがよさそう
はじめに
APIのドキュメントサイトを作らなくてはならないかもしれなくて調査中
ドキュメントの内容をDBで管理するって話もあって、それやるとメンテが面倒そう。。。
何かいいツールないかと思って探していたらapiDocというのを見つけた
http://apidocjs.com/
こちらでnode.jsで作られてる
処理の流れは以下のようなイメージ
・コードの中に所定のフォーマットでコメントを記述
・apidocコマンドを実行
・APIドキュメントの中身を配列で定義したjavascriptがつくられる
・ドキュメントサイトでそのjsonを読み込んで表示
で、今回やりたいこと
・見た目を多少変更したい
・見る人によって閲覧制限したい(人によって見れる・見れないドキュメントがある)
・時間かけたくない
基本的な使い方
1. apidocインストール
npm install apidoc
2. テンプレートコピー
cp node_modules/apidoc/template path/to/template
ここにテンプレートとなるHTMLとかjsとか入っているのでいじれば見た目とか細かい修正もできそう
/**
* @api {get} /user/:id 001 ユーザー情報取得
* @apiVersion 1.3.2
* @apiGroup User
* @apiPermission admin
* @apiParam {Number} id ユーザーID
* @apiSuccess {String} name 名前
* @apiSuccess {String} email Email
* @apiSuccess {String} password パスワード
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/4. apidoc実行
./node_modules/apidoc/bin/apidoc -i php_dir_path/ -o doc_dir_path/ -t template_dir_path/
で、こんな感じのかっこいいHTMLがつくられる
残りの閲覧制限は別でまとめる、以上です
