IG GROUP 開源 RESTdoclet 項目
IG GROUP已經開源了它的RESTdoclet Maven插件項目，該插件用于從基于Spring REST框架的服務中生成Web文檔。
為什么要開源？
REST（幸與不幸，取決于您的理解）沒有借鑒適用于SOAP服務的那種正式的WSDL協議定義，但在設計上，它嚴格遵守正式的接口規范。 服務操作直接遵照通用的Web規范，并不需要說明書：就像大家都知道的GET和POST操作。
可是，盡管REST操作可能比較好理解，但它所涉及到的數據類型可能就并非如此了。這些數據的準確文檔說明是這些服務能否被客戶成功采用的關鍵。
這并不是一個新的問題，雖然有一些像Swagger 和 I/O Docs這 樣的工具，能夠幫助從源碼直接生成API文檔，但通常這樣的工具不僅需要使用一個特殊的REST框架，也需要人工額外的配置。況且直到現在也沒有能比較方 便的使用于流行的Spring REST框架的工具（在我寫這篇文章時）。 IG GROUP RESTdoclet 的開發就是為了填補這一缺憾【1】，特別是在以下方面：
- 支持Spring 3 REST注釋和JavaDoc導出
- 不需要任何額外的注釋
- 在Maven的持續構建過程中，能夠很輕松的用最低的配置與之集成
- 支持多個數據流的服務開發
- 發布一個類似JavaDoc形式的互動文檔到網上，從而提供了一個與代碼無關的指南，服務于消費者 </ol>
- 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);
}</pre>
RESTdoclet要求你的源代碼必須在一個Maven Web工程里，既然它是一個Maven插件，所以它也需要在Maven中進行一些額外的配置。這些配置在多數情況下都是必須的，同時你也可以從RESTdoclet的用法頁面中復制這些配置信息。
配置完成后，執行命令：mvn install ,將生成Prestdoclet并且安裝服務元數據到你選擇的文件夾中，該文件夾路徑是通過環境變量中的RESTDOCLET_DEPLOY屬性定義的。
為了查看生成的文檔，你需要配置RESTdoclet Web應用到一個類似Apache Tomcat 的Web服務器上。Web應用程序將使用相同的RESTDOCLET_DEPLOY環境變量來定位一個或多個生成的服務的元數據，并將其顯示在Web瀏覽 器中，下面是截圖。
（點擊圖片將放大）
圖 1 – RESTdoclet service 摘要頁面
（點擊圖片將放大）
圖2 – RESTdoclet service 詳細頁面
從哪里可以得到它呢？
作為一個開源項目,可以從GitHub上下載RESTdoclet，也可以從Sonatype上以二進制的形式下載，二者都基于Apache2協議。
一定要閱讀項目Wiki的使用說明，假如您有任何疑問或反饋請隨時發email給IG GROUP，email地址是：open.source@iggroup.com。
關于IG Group PLC
IG GROUP是世界領先的金融點差交易和差價合約供應商。我們是FTSE 250的成員之一并且擁有1.7億美元的市值（截止到2011年6月）。
我們的總部位于倫敦，分公司遍布歐洲、美國、日本、新加坡和澳大利亞，我們的國際網絡還在迅速發展中，在過去的5年中里們已經開了11家分公司。
IG GROUZP在先進的交易技術、有競爭力的價格和可靠性方面已經建立了良好的信譽。我們已經贏得了很多獎項，并且一個獨立研究表明，有超過60%的英國活躍點差交易者持有帶IG Index的賬戶。【2】
【1】RESTdoclet是在Spring 3 REST框架宣布之前創建的，它最初設計是用來支持專有IG GROUP的REST框架，但Spring 3 REST成為主流之后 RESTdoclet代碼完全重構了。
【2】投資趨勢英國金融點差交易與合同差異報告（2011年11月）。
查看英文原文：http://www.infoq.com/news/2012/08/RESTDocletOpenSource
來自：http://www.infoq.com/cn/news/2012/09/RESTDocletOpenSource
怎樣使用呢？
比方說，你已經用Spring REST建立了一個REST架構的Java服務，像下面這樣：
/**