Web服务的文档标准/结构/样式

Question

有人可以推荐Web服务高级文档的指南吗？

这个文档应该允许不了解特定Web服务的人对其存在的原因，路线图及其使用示例有基本的了解。

此类文件应放在A4 / Letter纸的两面打印面上，并且需要不到10分钟的时间阅读。

请注意，这是开发人员用来使用接口的低级API文档的补充。

Answer 1

我不确定我是否有指南，但我可以向您展示我发现的一组Web服务API文档的示例。

http://www.flickr.com/services/api/

Flickr API页面以非常易读的形式展示。这个页面基本上有：

• 概述页面的链接
• 常见场景的撰写 （在此例中上传照片）
• 有关使用API​​的工具的信息
• 每个API的详细说明 方法，按活动分组

特别是，描述公共访问模式（上传照片，替换照片）的页面对我来说至关重要。它们会向您的API消费者展示如何执行常见操作以及您希望人们如何使用您的API。最后一点很重要 - 你想说“嘿，我们希望你这样使用这些方法来调用我们这种错误处理”。向用户展示一些关于API使用的最佳实践，您将为自己节省大量的支持电话。