交互式 I/O 文档——Mashery 重新定义 API 文档

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