このエントリでは、WebサービスのAPI開発を効率良く進めるために、
aglioとdrakovを使って、API仕様書とMockを生成する手順を整理したいと思います。

aglioはHTMLで仕様書を生成するツール、drakovはMockサーバです。

aglio | github
https://github.com/danielgtaylor/aglio

drakov | github
https://github.com/Aconex/drakov

これらのツールは、API Blueprintという
「API description language」（API記述言語って翻訳でよいのかな？）に従ったドキュメントから、
仕様書及びMockサーバを生成します。

環境の準備

ndenvでnode.jsをインストール

以下のように、ndenvでnode.jsをインストールします。

$ ndenv install v7.3.0

# ndenvについては、以下を参照。
# https://github.com/riywo/ndenv

作業ディレクトリの作成

以下のように、作業ディレクトリを作成します。
作業ディレクトリ以下で使用するnode.jsを指定します。

$ mkdir apiblueprint-sample && cd $_
$ ndenv local v7.3.0

npm initで「package.json」を作成します。
いろいろ聞かれますが、とりあえず全て既定値（ひたすらEnter）で回答しておきます。

$ npm init

サンプルのAPI仕様を作成

API Blueprintのトップページの内容そのままですが、
以下のようなAPI仕様のサンプルを作成します。

src/message.apib

# GET /message
+ Response 200 (text/plain)

        Hello World!

API仕様書の生成

aglioのインストール

npmでaglioをインストールします。

$ npm install --save-dev aglio

ドキュメントサーバの実行

以下のコマンドで起動し、ブラウザで3000ポートにアクセスすると、次のようなAPI仕様書を確認できます。

$ node_modules/.bin/aglio -i src/message.apib --server

ドキュメントの生成

以下のコマンドで、API仕様書のHTMLを出力することができます。

$ mkdir doc
$ node_modules/.bin/aglio -i src/message.apib -o doc/message.html

CIツールなどで、複数のapibファイルからHTMLを生成したい場合は、
gulp-aglioを使ってgulpから実行するとよいとかと思います。

gulp-aglio | npm
https://www.npmjs.com/package/gulp-aglio

Mockサーバの実行

drakovのインストール

npmでdrakovをインストールします。

$ npm install --save-dev drakov

Mockサーバの実行

以下のコマンドで、APIのMockサーバを起動できます。

$ node_modules/.bin/drakov -f "src/**/*.apib" --watch

以下のようにAPIを呼び出すと仕様に記載した応答を返却することが確認できます。

$ curl http://localhost:3000/message
Hello World!

localhost以外からMockを使用したい場合は、–publicオプションを使います。

$ node_modules/.bin/drakov -f "src/**/*.apib" --watch --public

参考にした記事

API Blueprintによるドキュメント開発環境【2016年冬】 | dackdive’s blog
http://dackdive.hateblo.jp/entry/2016/11/24/100000

Markdown で記述した API ドキュメントからお手軽にドキュメントサーバーとモックサーバーを生成する - Gulp で作る Web フロントエンド開発環境 #7 | NET BIZ DIV. TECH BLOG
https://tech.recruit-mp.co.jp/dev-tools/post-6138/