BT

最新技術を追い求めるデベロッパのための情報コミュニティ

寄稿

Topics

地域を選ぶ

InfoQ ホームページ ニュース IG GroupがRESTdocletをオープンソース化

IG GroupがRESTdocletをオープンソース化

ブックマーク

原文(投稿日:2012/08/13)へのリンク

 

IG GroupはSpring RESTベースのサービスからドキュメントを生成するMavenプラグインのRESTdocletのをオープンソースにした。

なぜ?

REST(幸か不幸か考え方によるが)はSOAPで利用されるWSDLの公式な規約を利用しない。RESTは設計上、正式なインターフェイスの仕様がない。仕様が必要ないウェブの汎用的なセマンティクスに従う。GETやPOSTは誰でも理解できる。

しかし、RESTの処理は理解しやすいものの、その処理で利用されるデータ型はその限りではない。サービスの利用者が正しくRESTサービスを使うためには、データ型について正確に記してあるドキュメントが重要だ。

これは新しい問題ではない。しかし、SwaggerI/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月)調べ。

 

この記事に星をつける

おすすめ度
スタイル

BT