のらねこの気まま暮らし

技術系だけど、Qiita向きではないポエムとかを書くめったに更新されないヤツ

Introduction to Hariko API Server with API-Blueprint

はい、harikoの紹介です。

harikoとは

hariko

harikoとはNodeJS製のAPI MockServerであり、APIドキュメンテーションツールであるAPI Blueprintのエコシステムです。

使い方

npmからインストールして下さい。

npm install -g hariko

harikoはAPI-Blueprintのドキュメントをベースにレスポンスを返すAPI Serverを立ち上げるので、 まずはAPI-Blueprintの仕様に沿ったmarkdownが必要です。

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

        hello world

適当に、 docs/api/message.md とかに保存します。

harikoのサーバを立ち上げます。 CLIから以下のように打ち込んで下さい。

hariko -f 'docs/api/*.md'
[INFO] Running Hariko Server ... http://localhost:3000

とshellがレスポンスしたらサーバの実行完了です。 ブラウザとかから http://localhost/api/message を叩いてみてください。 hello world と表示されるはずです。

harikoの機能たち

詳細はREADME.md とか見て下さいねって感じなんですけど、便利！！！と思って作った機能を幾つか紹介しませう。

markdownファイルの一部除外

drakovになくて地味に不便だったので入れた。 APIサーバに載せたくない一部ファイルを任意で除外するやつ。

glob形式で読み込む奴はブラックリストで弾ける用にしてほしい気持ち。

hariko -f 'docs/**/*.md'\
       --exclude 'docs/metadata.md'\
       --exclude 'docs/overview.md'

watch

ファイルを監視して、更新したらサーバを再読み込みします。 これは gaze をそのまま使ってます。gruntやgulpやらで使ってる奴。

gruntやらgulpやらのplugin書くときにいちいちreload書くの面倒でしょ？って思ったので。

hariko -f 'docs/**/*.md' -w

proxy

API-Blueprintに定義されていないパスにリクエストが飛んできたら、 指定したサーバにプロキシするオプション。

stubcellの全部のAPIリソースを一斉に移管するのが辛かったので、逐次移行できるようにしたいが為に用意したの。

application → hariko server → stubcell

hariko -f 'docs/**/*.md' --proxy 'http://localhost:8100'

output

これ！！！まじべんりだから！！！べんりだから！！！！ 指定したディレクトリにレスポンスデータを吐き出すオプション。

stubcellやeasymockみたいにJSONファイルを弄れば次のレスポンスから結果が変わるという、手動アプリケーションのための仕組み。 リロードしたら全部リセットされるので注意ね♪

hariko -f 'docs/**/*.md' -o 'api/'

verbose

ログレベルをverboseに設定します。 リクエストのデータとか、その辺のデバッグに使うといいかも？

ログ周りは自前だけどそれなりに気を配って書いた気持ち。

hariko -f 'docs/**/*.md' -v

harikoを作った背景

もともと、いまいる会社でSPA (Single Page Application) の開発で、UIファーストを実践していたのですが、どうにもAPIのドキュメンテーションが不足し、サーバとフロントエンドでやりとりの齟齬や過去のリソースについての確認があったり、まあ、ドキュメント欲しいよねって感じでした。（主に僕が

過去に easymock を使っていたのですが、ドキュメントの記法が独特で、メンテナンスもしばらくされていなかったので次のプロジェクトからは、 stubcell を使うようになりました。

どちらのツールも、JSONファイルをレスポンスとして返却してくれるツールだったんですが、 stubcellはJSON5に対応しているし、レスポンス内容を細かく設定できるしで好んで使っていました。

でもさすがに、JSON5だからといってjsonファイルにコメントアウトでドキュメンテーションするのは読みやすいとはいえない状況...

その当時(大体2015年の2月あたり？)からAPI-Blueprintの存在は知っていて、でもドキュメントMarkdownとは言いつつも学習コスト高そうだなぁ、エコシステムもどうなんだろうなぁと思っていたのでした。

時は経ち、「やっぱりドキュメント欲しいね」ってなって、改めてAPI-Blueprintを検証したのでした。

改めて調べてみるとエコシステムはなかなか充実しており、aglio なんかは美しいドキュメントを生成してくれて素晴らしいなぁと思っていたので、ついでに drakov というAPI Mock Serverがあるそうなのでそれも一緒にインストしました。

やーべんりべんり、と思っていたのはつかの間。 drakovを使っていた上で幾つか不便な点が出てきました。

  • mdファイルを監視してサーバをリロードしてほしい
  • mdファイルを一部除外したい
  • 検証用にうん万行のJSONデータを返すようにしたい
  • 存在しないAPIはstubcellで立てたAPIにproxyしてほしい

stubcellやらeasymockやらでやっていたファイルを書き換えたら次のリクエストで反映されたJSONが帰ってくるっていう状況は実に効率的だった...

という要望が積み重なってわっと作ったのが hariko というわけです。