交互式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？

InfoQ：能否请您描述一下有关将一个传统API文档，比如Java文档，迁移到I/O文档的相关技术细节？

 查看英文原文：Mashery Redefines API Documentation with Interactive I/O Docs