https://document360.com/blog/api-documentation/

当您购买新产品时，它会附带一本手册来指导您如何使用它。当你带回家打开你的新游戏机时，一定会想到里面有一本安装、使用和维护手册。当客户不知道如何使用产品时，他们就不太可能被公司留住或将来购买其他产品。

 API（应用程序编程接口）也不例外。当开发人员学习如何使用 API 时，他们需要一组说明才能成功。文档不是面对提交给支持团队的大量票据，而是在您的公司和最终用户之间提供了一个界面。

 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 与另一个系统交互的点被视为端点，并且可以包含服务器或服务的 URL。

状态和错误代码

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 的重要组成部分。

另请阅读： 敏捷 SaaS 文档：增强产品文档的 5 个关键原则 

API 文档最佳实践

1.采用清晰的语言

编写 API 文档时，您将不知道文档用户的专业知识水平。这就是为什么使用每个人都能理解的清晰、简单的语言很重要。

 2. 包含参考文档

API 的参考文档是 API 公开的对象和方法的完整列表，以及如何使用每个对象和方法的说明。这向开发人员介绍了所有可用的内容及其运作方式。

 3. 实施示例

您应该尽可能多地使用示例来说明 API 的工作原理，这些示例可以在文档的任何参考区域中找到。它可以是任何能够说明 API 概念并帮助开发人员进行自己的 API 调用的内容。

 4. 指定专人负责文档

您的团队中需要有人负责监督 API 文档的开发人员体验。如果他们是技术作家，这可能是他们的全部工作；如果他们也是开发人员，这可能是他们的兼职职责。

 5. 涵盖不同类型和主题

您需要确保您的 API 文档全面且涵盖参考、指南和示例。如果某些领域缺失，那么您将使用此信息来决定未来的工作重点。

 6. 将文档纳入流程

您的文档和 API 应该同步开发。随着 API 的发展，文档的开发也随之而来，尤其是随着新功能的发布。尽可能自动化并节省文档时间。

 7.提供快速入门指南

快速入门指南是让新开发人员了解您的 API 并让他们开始使用您的 API 的最佳方式。它们包含有关如何使用 API 的说明以及使访问 API 变得更加容易的代码示例。

Baklib是一个不错的选择，作为一个丰富的知识库软件，涵盖了不同类型的主题文档，强烈推荐您尝试！

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 来实现其目标。