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形式的互动文档到网上，从而提供了一个与代码无关的指南，服务于消费者
怎样使用呢？
比方说，你已经用Spring REST建立了一个REST架构的Java服务，像下面这样：
/**
* 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 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地址是：[email protected]。
关于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
感谢丁雪丰对本文的审校。
给InfoQ中文站投稿或者参与内容翻译工作，请邮件至[email protected]。也欢迎大家通过新浪微博（@InfoQ）或者腾讯微博（@InfoQ）关注我们，并与我们的编辑和其他读者朋友交流。