IG GroupはSpring RESTベースのサービスからドキュメントを生成するMavenプラグインのRESTdocletのをオープンソースにした。
なぜ?
REST(幸か不幸か考え方によるが)はSOAPで利用されるWSDLの公式な規約を利用しない。RESTは設計上、正式なインターフェイスの仕様がない。仕様が必要ないウェブの汎用的なセマンティクスに従う。GETやPOSTは誰でも理解できる。
しかし、RESTの処理は理解しやすいものの、その処理で利用されるデータ型はその限りではない。サービスの利用者が正しくRESTサービスを使うためには、データ型について正確に記してあるドキュメントが重要だ。
これは新しい問題ではない。しかし、SwaggerやI/O Docsのような情報源からAPIの仕様を生成するツールはあるものの、そのようなツールは特定のRESTフレームワークや追加の手動構成が必要だ。現時点ではSpring RESTフレームワークで簡単に使えるツールはない。
IG GroupのRESTdocletはこのギャップを解消するために開発された[1]。
- Spring 3 RESTアノテーションとJavaDocをサポートする
- 他のアノテーションは必要としない
- 最小限の構成でMavenに簡単に統合できる
- 複数のサービス開発の流れを支援する
- インタラクティブなJavadocのようなドキュメントをウェブへ発行できる。サービスのユーザに対してソースコードに依存しないドキュメントを提供できる
どのように動作するか
Spring RESTを使った次のようなRESTfulなサービスを開発したとする。
/**
* Find sample by unique lookup reference
*
* @param reference the sample reference, a 5 digit text field
* @return the sample object corresponding to the lookup reference
*/
@RequestMapping(value = "/samples/{reference}", method = {RequestMethod.GET})
@ResponseBody
public Sample getSampleByReference(@PathVariable String reference) {
return service.getSampleByReference(reference);
}
RESTdocletを使うにはソースコードMavenウェブプロジェクトに含める必要がある。RESTdocletはMavenのプラグインなのでpomに追加の構成が必要だ。この構成はほとんどの場合、同じ記述になり、RESTdocletの使い方紹介ページからコピーできる。
構成したら、mvn install –Prestdocletというコマンドを実行し、必須の環境変数RESTDOCLET_DEPLOYに設定したフォルダへサービスのメタデータをインストールする。
生成したドキュメントを見るために、RESTdocletウェブアプリケーションをウェブサーバへ配置する。このウェブアプリもRESTDOCLET_DEPLOY環境変数を見て、作成されたサービスのメタデータを配置し、次のスクリーンショットのようにブラウザで見れるようにする。
(クリックして拡大)
図1 – RESTdocletサービスのサマリページ
(クリックして拡大)
図2 – RESTdocletサービスの詳細ページ
どうすれば利用できるか
RESTdocletはGitHubからダウンロードできる。またSonatypeからバイナリを入手できる。両方ともライセンスはApache 2 ライセンス。
使い方はプロジェクトのwikiを参照。質問はフィードバックはIG Groupのメール(open.source@iggroup.com)でも受け付けている。
IG Group PLCについて
IG GroupはスプレッドベッティングとCFDを提供している。FTSE 250の構成企業であり、時価総額は17億ドル(2011年6月時点)。
ロンドンに本社を置き、ヨーロッパ、アメリカ、日本、シンガポール、オーストラリアにオフィスがある。今後5年間で11の新しいオフィスを開設する。
ドレードに関する先進的な技術、価格競争力、信頼性で高い評価を確立している。受賞歴多数。独立調査によれば、イギリスのアクティブなスプレッドベッティングの利用者の60%以上がIG Indexの口座を持っている[2]。
[1] RESTdocletは was built before Spring 3 RESTのアノテーションが利用できる前に開発された。最初はプロプライエタリなIG Group RESTフレームワークをサポートしていたが、Spring 3 RESTが主流になると後に完全に書き直された。
[2] Investment Trends UK Financial Spread Betting & Contracts for Difference Report (2011年11月)調べ。