Apiblueprintを使ってみた

APIBlueprintとは

公式ドキュメント

https://apiblueprint.org/documentation/tutorial.html

APIの仕様をMarkdown記法で記述できる言語。また、aglioコマンドで自動でHTMLファイルを生成しブラウザ上で閲覧ができる。

特徴

• API設計書のテンプレートとして使える
• テキストベースなのでgit管理しやすい
• ローカルにモックサーバーを立てることができテストしやすい

導入

Homebrewのインストール

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

バージョン確認

brew -v

nodebrewのインストール

brew install nodebrew

バージョン確認

nodebrew -v

node.jsインストール

// インストール可能なバージョンの確認
nodebrew ls-remote
// インストール先のディレクトリを作成
mkdir -p ~/.nodebrew/src
// 最新の安定版をインストール
nodebrew install-binary stable
// インストールされたバージョンを確認
nodebrew ls
// 使用するバージョンを指定
nodebrew use v12.14.1
// パスの設定
echo 'export PATH=$PATH:/Users/[ユーザー]/.nodebrew/current/bin' >> ~/.bashrc
// 反映
cd
source .bashrc

バージョン確認

node -v
npm -v

aglioのインストール

npm install -g aglio

とりあえず環境構築は以上。

使ってみる

記法に従って仕様書を作成する。拡張子は.apibで保存する。

aglioコマンド

ローカルサーバーを起動する

localhost:3000にアクセスすると指定した.apibファイルがブラウザ上で閲覧できる。

.apibファイルを編集すると変更がリアルタイムで反映される。

aglio -i <filename.apib> -p 3000 --server

// 終了する場合
control + c

HTMLファイルとして吐き出す

サーバーは起動せずHTMLファイルを出力する。

aglio -i <filename.apib> -o <output.html>