API仕様書をAPIblueprintを使って作り、ブラウザに表示させるまで
参考1、API blueprint自体はツールではなく、このmarkdown記法にのっとったファイルを、他のツールでhtmlに変換する
node.jsのパッケージ管理ツールである、npmをインストール
macでnpmがインストールできないときは、アンインストールしてから再インストール
aglioをインストール
aglioとは?
API blueprintに沿ったmarkdown形式のファイルをhtmlに変換し、
サーバーを通じてブラウザでHTMLで表示出来る。
https://qiita.com/kai_kou/items/630f6c1e4e577518bd14
参考2、aglio起動方法
参考3、aglioディレクトリに変換したい元のファイルを作成する
aglioをインストール
npm i -g aglio
インストールできたら、API blueprintのフォーマットに沿って書いたファイルを、aglioをインストールしたディレクトリと同じ所に保存する(今回はアプリのルートディレクトリにした)
サンプルファイルを作成
$ touch apiblueprint.md(ファイル名はなんでも良い)
作ったファイルを、API blueprintのmarkdown記法で記述する
# GET /message
+ Response 200 (text/plain)
Hello World!
作ったファイルをHTMLファイルに変換するため、以下をターミナルで入力
(-o オプションで出力を指定出来る)
aglio -i 作ったファイル名 -o XXXX.html(出力先のファイル名。HTMLであればなんでも良い。このファイルも同じディレクトリに作成される)
ターミナルで以下を入力し、ドキュメントサーバーを起動
$ aglio -i 作ったファイル名 --server
Server started on http://127.0.0.1:3000/
Rendering apiBlueprint.md
Socket connected
サーバーが立ち上がるのでlocalhost:3000へアクセス
するとHTMLに変換されたAPI仕様書をブラウザで見ることが出来る。
まだ80番では出来ていない。
aglioでwebサーバーを立ち上げることのメリット
・aglioが動いているホスト/ポートに対してHTTPでリクエストすることで、HTML化されたドキュメントを取得することができる
・Webサーバが立ち上がっている状態で、API Blueprintのコードを編集すると、即座に再ビルドがかかり常に最新の状態になる
・再ビルドがかかった際にブラウザでドキュメントを表示していると、ブラウザも自動で再読込がかかる
メモ
~/.npm配下の全てのディレクトリのオーナーを自分自身に変更する
(whoamiは自分のユーザー名を表示するコマンド)
sudo chown -R `whoami` ~/.npm