読者です 読者をやめる 読者になる 読者になる

【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とか入っているのでいじれば見た目とか細かい修正もできそう

3. PHPのコメントにAPIのコメント記述

/**
 * @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/

f:id:yoppy0066:20160820021826p:plain
で、こんな感じのかっこいいHTMLがつくられる

残りの閲覧制限は別でまとめる、以上です

※追記
【node.js】apiDocにパーミッションごとに閲覧制限する方法 - とりあえずphpとか
まとめた