こんにちは。最近は会社の技術研修を粛々と受けています。 6月に入ってからはRailsチュートリアルを進めていて、ちょうど先週に終わりました。Railsは大変多機能であるとヒシヒシ感じています。 Ruby自体も今まで書いたことがなかったので、私の経験のある言語とは結構毛色が違っていて面白い気分です。 残業も特になく給料をいただきながら勉強している謎の身分ですが、権利をありがたく享受してスーパーエンジニアに成長したいと思います。
そんなこんなとは別で、趣味で最近作り始めたのがcurldocというツールです。
curldoc
curldocのcurlはコマンドのcurlから来ています。 平たく言うと、curlコマンドとそのレスポンスを記述したMarkdownファイルを読み込んで立ち上がるモックサーバを作っています。
そもそもcurlはHTTPリクエスト1を送ることができるコマンドですが、実はこれ、ただ単なるコマンドだけでなく、HTTPリクエストを表す汎用的なフォーマットなのではないかと思っています。 PostmanやChrome開発者ツールにも、送信したリクエストをcurl形式で書き出す機能があったりします。
curldocの仕様書の形式
これをもとに、curlコマンドとその実行結果を書いたら簡易的なAPI仕様書になります。2 例えば次のような、リクエストとレスポンスのペアをひたすらMarkdownファイルに記述します。
リクエストを以下に記す。
```curldoc-request
curl http://localhost:3000/hello --header 'Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l'
```
レスポンスを以下に記す。
```curldoc-response
{
"message": "hello"
}
```
この形式のよいところは2つあります。
シンプル
１つ目はシンプルであることです。 curlコマンドは前述のようにGUIアプリケーションから書き出せるし、広く普及しているフォーマットでもあります。
APIドキュメントを記述する形式としては例えばSwaggerなどが既にあります。 大変良くできたツールであると思いますが、どうしても記法を学んだり、対応するツールがある言語やフレームワークの上でしか使えなかったりと、場合によっては多機能すぎることもあるでしょう。 小さなアプリケーションを作る場合やハッカソンで素早く作る場合、社内向けツールでドキュメント整備の優先順位が低い場合など、APIの仕様を簡単にテキストにまとめるほうが良い場合もあるのではないでしょうか。 curldocはまさにそれです。 なるべく知識を必要とせず、簡単に、しかし齟齬無く最低限の要求を満たすAPIドキュメントの形式がcurldocです。
シンプルであるからこそ、JSONだろうがXMLだろうがHTMLだろうがHTTPであれば自由に記述できます。
実行可能
2つ目は実行可能であることです。 curlコマンドは本来はコマンドですから実行可能です。 シェルに貼り付けてエンターを押せば試せます。 HTTPサーバを開発してデバッグする時、テストする時、既に開発されたものを使ってみるとき、コピペしてエンターを押すだけで試せるなんてなんと素晴らしい仕様書でしょうか。
片手落ちの「実行可能」の片手を作る
ここまでは単に「curlコマンドの形式でドキュメントを記述すると楽だよ」という話でした。 しかし、2つ目の実行可能であるという点は片手落ちです。 もともとAPI仕様書はクライアント側とサーバ側で認識を合わせるため、双方のためにあります。 しかしながらcurlコマンドはクライアントなので、実行可能であるのは片方の立場だけです。 サーバを開発する人はcurlコマンドで確認できますが、クライアントを開発する人は実際のサーバができあがるまで実行できません。
そこで出現するのがcurldocです。 curldocはAPI仕様の書かれたMarkdwonファイルを元にモックサーバを立ち上げます。 Markdownファイルに書かれたものと同様のリクエストが来たら、対応するレスポンスを返すだけのモックサーバです。 curldocというアプリケーションによって、上記の形式のAPI仕様書が、クライアントサイドにとってもサーバサイドにとっても実行可能になることでしょう。
モックサーバなので、開発にもテストにも用いることができるはずです。34
これから
まだ作りかけのアプリケーションについて雄弁に語ってしまいました。 現状でも一応ベーシックな機能としては動いていて、Markdownファイル上でHTTPのヘッダやボディを指定すると比較してくれたりします。 とはいえやりたいことは以下のようにまだまだあります。
- JSON形式のリクエストボディの比較を柔軟に行う
- 指定されなかったHTTPレスポンスヘッダをよしなに埋める
- ライブラリとして提供できるインタフェースを追加する
- ドキュメントを書く
- npm publishする
- curlオプションのサポートを増やす
頑張って作るぞ。
https://github.com/yammerjp/curldoc.git
Footnotes
-
curlはHTTPに限らず様々なプロトコルをサポートしているようです。なんでも出来すぎてびっくりするくらい。 ↩
-
もともと5月末にハッカソン的にWebアプリケーション開発をやったときの感想から生まれたアイデアのツールです。サーバサイドとフロントエンドを別の人間が開発するとき、APIの認識をさくっとあわせるにはcurlコマンドによるリクエスト例を記述していく方法が結構はかどりました。 ↩
-
モックサーバを必要とするのはクライントアプリケーションだろう。→クライアントアプリケーションといえば特にWebではJavaScriptだろう。→ JavaScriptのテストで用いるならJavaScriptから起動できたほうが良いよねということでNode.jsで作っています。コマンドだけでなくライブラリとして提供したいと思っています。 ↩
-
別に作っているAtomPubのクライアントのテストが結構汚くて、JSONではないAPIクライアントのモックサーバが欲しくて作っている側面もあります。 ↩
古い記事