原文链接：https://document360.com/blog/api-documentation/
当你购买一件新产品时，它会附带一本说明书，指导你如何使用。你不会希望把新买的游戏机带回家开箱后发现没有一本关于设置、使用和维护的手册。如果客户不知道如何使用产品，他们就不太可能被公司的产品吸引或在未来购买其他产品。
API 也不例外。当开发人员在学习如何使用 API 时，他们需要一套说明书才能成功看懂。文档应该在公司和最终用户之间提供了一个接口，而不是等到面对提交给售后团队的大量工单。
API 的提供商有义务提供相关、具体和最新的 API 文档，并且与你产品的开发进度保持一致。如果开发人员不了解如何使用 API，那么 API 再好也没什么用。
什么是 API 文档？
API 文档是一份说明书，它告诉开发人员以及其他相关人员如何使用你的 API 以及其服务来实现特定目的。API 文档 通常包含代码示例、教程以及有关函数、类和返回类型的详细信息。从本质上讲，它为开发人员提供了与应用程序接口建立集成和使用软件进行应用程序接口调用所需的所有信息。
API 调用是第三方开发人员向平台的 API 发出的一种请求。文档中对 API 如何调用进行了描述，告诉开发人员可以让 API 做什么以及如何去做。
API 文档清楚地展示了其端点，解释了为什么要使用这些端点，并给出了如何使用这些端点的具体示例。
API 之所以重要，是因为它意味着开发人员不必从头开始一遍又一遍地构建相同的软件解决方案，开发人员可以利用已经实现的其他平台，并将其功能集成到自己的程序中。许多大型平台都有自己的 API，例如 Twitter 和 GitHub。
API 的类型
面向团队
你可能有一个公司内部的 API，仅供团队内的成员使用。这类 API 的目的是简化团队和系统之间的数据传输，因此你的公司内部开发人员必须使用这类 API。
面向合作伙伴
合作伙伴的 API 可以在组织外部共享，但只能与那些与提供 API 的公司有业务关系的人共享。只有经授权的客户才能访问 API，因此这类 API 的安全措施往往更为严格。
面向最终的用户
面向用户的 API 可以被任何开发者使用，不受任何限制。这类 API 没有特别严格的验证和授权措施，因为提供商希望尽可能多的开发者采用 API。有时这类 API 需要支付订阅费，订阅的费用根据调用 API 的次数进行分级。
谁来编写 API 文档
由于开发者是实际构建 API 的人，因此他们通常会承担编写文档的任务。但不幸的是，开发者驱动的文档往往过于技术化，因为开发者已经非常了解业务。由于开发者实际上更专注于构建和维护 API，因此由他们编写的文档也可能被弃置一旁。因此，许多公司都聘请专业技术撰稿人来编写 API 文档。技术撰稿人具备理解 API 的技术能力，还具有为终端用户撰写引人入胜内容的创造性。
API 开发者向技术撰稿人提供准确记录 API 所需的信息。如果文档中缺少哪个部分，开发者可以帮助技术撰稿人补齐，最终为目标受众提供一份清晰易懂的文档。
API 文档的好处
增强 API 的开发人员体验
首先，API 文档可以改善开发者的体验。如果潜在开发者不了解如何使用 API，那么 API 再好也没有用。一份良好的 API 文档可以帮助开发者了解它所提供的不同端点，以及特定用例的示例。当你开始改善开发者体验时，就能够增加产品所能吸引的潜在用户数量。
减少内部开发者或外部合作伙伴的上手时间
良好的 API 文档意味着你们的售前和客户成功团队只需花费较少的时间，就能让新的内部开发者或外部合作伙伴快速上手。新的 API 用户可以通过文档获得他们所需的所有信息，以便开始使用你的平台。有了文档化的流程，就不需要特定的团队成员进行干预。
高效的产品维护和更快的迭代
当你有效地记录 API 时，意味着你可以更快地管理产品的维护和更新。有了 API 文档，你就能清楚地知道你的产品需要做什么，以及它应该如何帮助用户。文档可以让你更直观地了解 API，让你可以更快地推出被用户采纳的新版本。
帮助内部和外部用户理解 API 及其功能
API 文档的主要好处之一是可以帮助内部和外部用户了解 API、API 的用途以及你如何为自己的目的部署 API。如果你不解释 API 的潜在功能，那么新用户就不知道如何使用它，这样就会遇到产品上手缓慢的问题。API 的潜在用户会将文档作为决定是否使用你的产品的一种方式。
团队成员查阅 API 权威渠道
当组织内部团队成员想要熟悉 API 的目标时，他们可以参考 API 文档。即使那些没有直接参与 API 构建或文档编写的人员，也能理解 API 的预期目的，并能够支持 API 开发者的工作。
允许快速识别错误和问题
当你维度 API 文档时，可以让你在测试 API 以记录其所有功能的过程中快速发现错误和问题。如果你的 API 不能按设计正常运行，可以反馈给 API 开发者，他们可以采取措施来解决任何问题。最终 API 将更加专业和有效，并按照预期运行。
API 文档的结构--设计与功能
大纲： API 文档的大纲也称为概述。它包含 API 及其用途的摘要，并可能告知潜在用户使用此 API 相对于其他 API 的好处。
教程： 教程是 API 的主要组成部分，其目的是向用户传授 API 的概念以及如何有效使用 API。它通常包含如何集成 API 以及如何正确运行的分步指南。
认证： 身份验证是提供商为开发者和最终用户保证 API 数据安全的方式，因此它可能有多种身份验证方案。API 文档会解释每种身份验证方法，以便用户了解如何访问 API。
**端点定义：**API 端点定义是 API 与应用连接的点。API 与另一个系统交互的点被视为端点，可以是服务器或服务的 URL。
状态码和错误码： API 使用状态码和错误码来通知开发者 API 的性能与预期不符，同时还提供状态或错误的说明，它可以包含如何继续操作和如何解决遇到的错误的说明。
例子： 当用户了解 API 的工作原理后，最好能给他们提供一些示例，展示调用、响应、错误处理和其他操作的成功示例，这些都是他们在使用 API 时可能会遇到的。
**词汇表：**与其在整个文档中解释每一个技术术语，你都可以链接到一个词汇表，其中提供了术语、schema 等的定义。
如何编写你的第一个 API 文档
识别受众
在开始创建任何类型的 API 文档之前，你应该确保了解你的产品的目标受众。你必须清楚地知道你想要关注的用户类型、他们将从 API 中获得的特定好处以及他们在现场使用你的文档的方式。
重要的是要记住，你的 API 文档的潜在受众通常可以分为两类。
第一类是将与 API 互动并积极使用 API 的开发者，他们需要更多的教程和代码示例类文档。
第二类受众是技术领导和产品经理，他们将评估 API 及其与业务目标的一致性。
创建用户旅程图
当用户与你的 API 文档交互时，他们可能正处于用户之旅的某种阶段之一。初次评估你的 API 的用户时，需要文档来告诉他们你的 API 能做什么、能解决什么问题、功能和端点的定义以及你的 API 与其他提供商的不同之处。
创建用户旅程地图可以让你满足处于不同阶段的用户的需求，并提供更好的开发者体验。开发者的每一步都将得到支持，而不是想知道你的 API 能为他们做些什么。
从常见场景指南开始
有一些最常见的功能会用到你的 API，因此你可以为这些场景创建指南。你必须确保解决你的 API 的典型使用案例，这样新开发者才能了解如何正确使用 API。每个用例都应有一个单独的部分，并在每个用例中包含一条示例消息。
为常见情况提供指导将有助于你的开发者快速上手，而不用自己费力去严谨。它还能向开发者展示你的 API 的能力，并说服他们选择你的 API 而不是其他 API。
添加代码示例
在你的 API 文档中添加代码示例有助于开发者快速上手试用你的 API，并了解其全部的能力。每个端点都应附带自己的代码示例，这样开发者就可以根据自己的具体要求定制代码，并试用端点最重要的功能。
代码示例可以向潜在开发者展示你的 API 是如何工作的，让他们更容易上手，因为只需复制并粘贴代码即可。你可以在 API 中包含所有不同编程语言的代码示例。
标注错误信息和状态码
错误信息和状态码应该包含在你的文档中，因为它们会告诉你的开发者，他们什么时候成功调用了 API，什么时候没有调用。每条消息或代码都应包含简要说明，说明显示的原因，以便用户了解与系统交互时发生的情况。
维护你的文档
在首次发布文档后，你需要确保定期重新查看文档，以保持内容的实时性。没有什么比不完整或不准确的文档更让你的潜在 API 用户更反感的了。
如果不长期保持有效的文档，开发者将无法使用你的 API，API 的采用率也随之会下降。每次更新或发布新功能时，都应在文档中有所体现，并将其视为发布 API 的重要组成部分。
API 文档最佳实践
使用通俗易懂的语言
在编写 API 文档时，你会不知道文档用户的专业知识水平。因此，使用每个人都能理解的清晰、通俗的语言非常重要。
包含参考文档
API 的参考文档是 API 公开的对象和方法的综合列表，以及如何使用每个对象和方法的说明。这可以让开发者了解哪些是可用的及其操作方法。
实现示例
你应该尽可能多地使用示例来说明 API 的工作原理，这些示例可以在文档的任何参考区域中找到。它可以是任何能够说明 API 概念并帮助开发者开始调用 API 的示例。
派专人负责文档
你的团队中需要有人负责监督 API 文档的开发者体验。如果他们是技术撰稿人，这可能是他们的全部工作；如果他们也是开发者，这可能是他们的兼职职责。
涵盖不同的类型和主题
你需要确保你的 API 文档是全面的，并且涵盖参考资料、指南和示例。如果某些方面存在缺失，你就可以利用这些信息来决定今后的工作重点。
将文档整合到自动化流程中
你的文档和 API 应该同步给开发者。随着 API 的开发，你的文档也要随之跟新，尤其是在发布新功能时。所以要尽可能实现自动化，节省你的文档编写时间。
提供快速入门指南
快速入门指南是让新开发者加入你的 API 并开始使用你的 API 的最佳方式，它包含如何使用 API 的说明以及代码示例，让访问 API 变得更加简单。
API 文档的最佳示例
GitHub API
GitHub API 是一个 REST API，开发者可以用它与软件项目协作开发工具 GitHub 平台连接。GitHub 提供了详尽的快速入门文档，帮助开发者掌握 API 的使用，并针对使用 API 的各个方面提供了详细的章节。
Twilio API 文档
Twilio 的 API 是另一个 REST API，开发者可利用它与 Twilio 平台连接，Twilio 是一个客户参与平台，可帮助企业进行大规模通信。该文档包含集成 Twilio 所需的所有内容，包括如何使用 HTTP 和 SDK 进行身份验证。
Dropbox API 文档
Dropbox 的 API 使开发者能够创建与 Dropbox 文档共享平台的集成。它提供组件，帮助用户嵌入 Dropbox 组件，同时还提供了 API 参考，使开发者能够构建和集成自定义应用，还为流行的编程语言提供了多个官方 SDK。
总结
仅仅构建 API 还不足以确保产品的采用--你还需要提供全面的 API 文档，向你的潜在用户和现有用户展示如何使用你的工具。如果没有人了解你的 API 要做什么，就不会有人有动力去使用它，你就会错失很多潜在的利润。即使你的 API 是非营利性的，你仍然希望最大限度地增加你的 API 的用户数量。
在创建 API 文档时，请仔细考虑你的潜在用户，如何能够帮助他们充分利用你的工具的内容类型。必须满足所有最常见的使用场景，并预测用户在尝试使用 API 时最有可能遇到的障碍。
提供 API 是扩展你的产品功能和接触大量新用户的绝佳方式。文档是连接你的 API 和用户的桥梁，他们将使用你的 API 来实现自己的目标。
更多 API 管理及 API 全生命周期相关内容可以在我的 Notion 查看，我将会持续更新：API 全生命周期管理资料