终涵盖以下主题： API 概述 所有 API 文档都应从 API 概述开始。通常，这可能非常简短，因为 API 的名称应该已经告诉您该 API 的用途。例如，在 AWS Lambda 文档中，DeleteAlias API 的概述只有一句话。 但是，重要的细节应始终在 API 概述中注明。例如，在忘记密码 API的 ClickSend 文档中，概述包含几个简短的段落，详细说明了使用说明。 忘记密码 API 的 ClickSend 文档 端点和方法 REST API 必须包含端点，它告诉开发人员如何访问资源。因为这是 API 参考的关键部分，所以使其从文本的其余部分中脱颖而出通常是有意义的。除了端点之外，还请确保包含受支持的方法，例如 GET 和 POST。 接口参数 您的文档需要列出所有 API 输入参数。对于每个参数，您应该包括输入类型、简短描述、接受的值（即正则表达式 [Regex]，如果适用）以及该字段是否为必填。您可以在 ClickSend 的发送帐户验证 API文档中看到这些属性都清楚地列出。
发送帐户验证 API 的 ClickSend 文档 API响应 当然，您还应该包含 API 响应。在 ClickSend 文档中，它包含 瑞典 WhatsApp 号码列表 在主代码示例下方的最右侧面板中，与删除联系人 API的情况一样。 删除联系人 API 的 ClickSend 文档 代码示例 阅读您的 API 文档后，您的读者在调用您的 API 时应该没有问题。通常，说明这一点的最佳方法是通过代码示例。正如我们在前面的三个示例中所看到的，ClickSend 在最右侧的面板中包含许多主要编程语言的代码示例。 其他必需品 您的 API 文档还应充分包含并描述以下内容： 状态码和抛出的异常类型 认证方式 限制，例如参数的最小值和最大值 速率限制，例如允许用户发出的最大 API 请求，直到受到限制 变更日志或弃用通知（如果适用） API 文档最佳实践 要编写尽可能最好的 API 文档，您需要的不仅仅是要包含哪些内容的实用知识。创建和更新文档时，请记住以下最佳实践。 未雨绸缪 在写任何东西之前，提前计划总是有帮助的。这意味着首先起草一个大纲（是的，这甚至是文档编写的最佳实践之一）。
有了完整的大纲，您忘记在文档中包含某些内容的可能性就会大大降低。 提前计划还可能涉及考虑文档的最终布局。您可能有表格来组织输入参数和返回值。您还可以考虑使用两列或三列布局，这两种布局都是当今业界流行的格式。例如，Stripe 的 API 文档包含三列布局，类似于 ClickSend。如下所示，ClickSend 在左侧列出了 API 操作，在中间列出了主要 API 描述，在右侧列出了代码示例。 ClickSend 三栏文档布局 三个C 每当您尝试通过 API 文档进行交流时，您都可以使用三个 C作为编写指南： 请明确：技术概念很快就会变得复杂。最重要的是，文档需要清晰。目标是达到六年级阅读水平的写作水平。 保持简洁：尽可能使用较短的句子。让你的观点直接而简单。 保持一致：您的文档在所有 API 中都应该在布局和风格方面保持一致。如果多人为 API 文档做出贡献，请考虑遵守通用风格指南。 避免使用技术术语 你不会因在文档中充斥技术术语而获得奖励。
發表於 2024-5-14 12:55:37
