Developers開発の実験等々、クイックサーブのメンバーが好き好きに書き込んでいく場所です。Blueprintで記述されたAPPI仕様からドキュメントとなるHTMLを生成したり、Webサーバとして動作することでドキュメントサーバを構築できるaglioを用いて、Debian上にAPIドキュメントサーバを構築してみたのでその備忘録。Blueprintは、WebAPIの仕様を記述するための言語。World!”が返却される」というAPIの仕様を表現している。Blueprintには様々な構文が用意されている。その辺りはドキュメントが豊富なので、Exampleに目を通してみるとイメージが付くかもしれない。Blueprintを使用することで、表現力豊かなAPI仕様を書くことができ、素早い設計やプロトタイプの構築を行えるようになる。関連ツールを用いることで、ドキュメントサーバを構築したり(本記事)、APIの自動テストを生成したり、APIのモックを用意できたり、はては実コードの生成まで行うことができる。Blueprintで書かれた仕様を元にHTMLを生成したりWebサーバを立ち上げることで、APIドキュメントサーバを構築することができる。Blueprintによる仕様からのドキュメント生成、ドキュメントサーバの起動までを行う。aglioのインストールnpmでaglioをインストール。cacheその後再度インストールで解決。適当なディレクトリで、input.mdを作成する。Blueprintで記述したMarkdownファイルからHTMLファイルを生成する。oオプションで出力を指定できるので、output.htmlにしておく。output.html出力されたoutput.htmlをブラウザで開くと、以下のようにドキュメントが生成されていることがわかる。204以下のように柔軟にAPIの仕様を記述、ドキュメントの構築を行うことができる。前述の方法だと、作成中は毎回コマンドを叩いてHTMLを生成して、ブラウザを再読込してとひと手間かかるし、ドキュメントを公開するのも面倒だ。そこで、aglioのWebサーバ機能を用いて、ドキュメントサーバを立ち上げる。connectedWebサーバが立ち上がり、ブラウザでアクセスしている状態で、エディタでコードを変更すると、以下のようにリアルタイムに再ビルド、ブラウザ更新が行われる。Blueprintとaglioでこんなことが出来るよと触り程度紹介したので、実際に使って見るには情報が不足している。興味が湧いた人は以下のリンクからさらに調べてみると、より丁寧に書かれているので、さらに理解が深まるはず。コメントをキャンセルメールアドレスが公開されることはありません。