IG GROUP 开源 RESTdoclet 项目

  • Robert Morschel
  • 孙浩

2012 年 9 月 17 日

话题:REST语言 & 开发架构

IG GROUP 已经开源了它的 RESTdoclet Maven 插件项目,该插件用于从基于 Spring REST 框架的服务中生成 Web 文档。

为什么要开源?

REST(幸与不幸,取决于您的理解)没有借鉴适用于 SOAP 服务的那种正式的 WSDL 协议定义,但在设计上,它严格遵守正式的接口规范。 服务操作直接遵照通用的 Web 规范,并不需要说明书:就像大家都知道的 GET 和 POST 操作。

可是,尽管 REST 操作可能比较好理解,但它所涉及到的数据类型可能就并非如此了。这些数据的准确文档说明是这些服务能否被客户成功采用的关键。

这并不是一个新的问题,虽然有一些像SwaggerI/O Docs这样的工具,能够帮助从源码直接生成 API 文档,但通常这样的工具不仅需要使用一个特殊的 REST 框架,也需要人工额外的配置。况且直到现在也没有能比较方便的使用于流行的 Spring REST 框架的工具(在我写这篇文章时)。 IG GROUP RESTdoclet 的开发就是为了填补这一缺憾【1】,特别是在以下方面:

  1. 支持 Spring 3 REST 注释和 JavaDoc 导出
  2. 不需要任何额外的注释
  3. 在 Maven 的持续构建过程中,能够很轻松的用最低的配置与之集成
  4. 支持多个数据流的服务开发
  5. 发布一个类似 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 地址是: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


感谢丁雪丰对本文的审校。

给 InfoQ 中文站投稿或者参与内容翻译工作,请邮件至editors@cn.infoq.com。也欢迎大家通过新浪微博(@InfoQ)或者腾讯微博(@InfoQ)关注我们,并与我们的编辑和其他读者朋友交流。

REST语言 & 开发架构