Mashery 于 2011 年 7 月 25 日发布了其I/O 文档工具,这也是对Mashery API 管理SaaS 平台提供的新增支持。 I/O 文档旨在为开发人员提供一个接口,通过该接口可以直接在 API 文档中执行实时 API 调用,从而实现加速应用。
针对该工具及其特点,InfoQ 对 Mashery 产品管理主管 Neil Mansilla 进行了采访。
InfoQ:什么是 I/O 文档?该项目的动因又是什么呢?
Mashery I/O 文档是一种交互式的文档,可以帮助开发人员更加快速有效地理解和学习 API。我们可以直接从 API 文档执行实时的 API 调用,相较干巴巴的静态示例这种方式可以提供实时的载荷数据。I/O 文档能够帮助我们的客户和 API 提供者,这样发布的文档外观清晰、简洁,且在内容资源、方式方法和参数层面又能够做到细致入微。
在我们此前的调研中,我们了解到 API 文档通常缺乏方法上的专用性和 API 调用样例。使用 Mashery I/O 文档,对方法的分析,可深入到参数层次,从而为开发人员良好地定义并清晰地展现出来。至于 API 调用样例,I/O 文档就是个实时样例生成器——通过实时 API 调用,开发人员能够创建自己直接可运行的样例。我们推出 I/O 文档的动因就是希望能够帮助我们客户的平台和开发人员取得成功。
下面列举了该工具其他一些对 API 提供者带来的好处:
- 清晰的 API 文档,测试、调试以及开发都集中在一起
- 缩短开发人员首次 API 调用时间
- 更快的应用开发
- 减少技术支持
- 具备一个强大的沟通渠道可供内部技术支持、QA 以及技术写手来实现与 API 变更的交流
- 确保 API 文档反应当前的 API 版本
- 清晰、优美的 API 文档设计
InfoQ: 该工具是否同样适用于公共 API 和企业内部 API 呢?是否支持非 REST(non-RESTful)APIs?
Mashery I/O 文档对私有企业 API 和公共 API 都适用。Mashery I/O 文档目前支持 RESTful APIs。很快 I/O 文档将实现对 SOAP 的支持。Mashery I/O 文档是可扩展的,并且能够适用于支持非标准的协议。
InfoQ:能否请您描述一下有关将一个传统 API 文档,比如 Java 文档,迁移到 I/O 文档的相关技术细节?
Mashery I/O 文档使用一种 JSON schema 来描述 API 资源、方法和参数。该 schema 可被扩展来处理各种 API 的各种独到特征。创建一个面向 I/O 文档的 JSON 配置是最直截了当的方法。
InfoQ:还有什么有关 IO 文档未来发展蓝图是您觉得可以与社区分享的吗?
我们的 I/O 文档发展蓝图包括:提供补充加密方法的支持、支持 SOAP、能够实现随地部署(甚至在 Mashery 环境堆栈以外)。
一些早期的 I/O 文档实现已经可以公开获得了,其中包括从
Klout 、
Alibris 以及
Fanfeeder 获取 API 文档。
查看英文原文: Mashery Redefines API Documentation with Interactive I/O Docs
评论