如何编写API文档：14条基本准则

文档通常是编程世界中理解的基石，API 也不例外。如果没有结构良好的文档，API 可能会像外语一样难以理解。虽然编写用户友好的 API 文档具有挑战性，但只要方法正确，就可以实现，并且可以大大提高 API 的可用性。

精心编写的 API 文档不仅仅列出端点、参数和响应格式等技术细节。它提供必要的上下文、示例和实际用例，使开发人员能够快速了解​​和利用 API 的功能。这种形式的文档不仅仅是一份技术指南；它还可以作为一份全面的参考资料，使开发人员能够在应用程序开发中高效地利用 API。

有效的 API 文档不仅概述了 API 的技术方面，例如端点、参数和响应格式，而且还提供了上下文、示例和用例，以帮助开发人员快速掌握 API 的概念和功能。它充当参考指南，使开发人员能够构建准确高效地利用 API 功能的应用程序。

创建高质量的 API 文档需要在技术准确性和清晰简洁的语言之间取得平衡。它应该适合不同技能水平的开发人员，从初学者到经验丰富的专业人士。记录良好的 API 不仅可以改善开发人员的体验，还可以促进 API 的成功和采用。

现在，只有 32% 的 API 提供商相信他们的 API 文档高于平均水平，我们认为详细说明最佳方法并给出令人信服的理由，说明为什么您应该始终为您的 API 提供出色的文档至关重要。

API 文档的关键统计数据

首先，让我们了解 API 文档的一些关键统计数据：

* ProgrammableWeb 的一项研究发现，70% 的 API 开发人员表示文档是他们决定使用 API 的最重要因素。

* Mulesoft 的另一项研究发现，45% 的 API 开发人员表示，他们不得不因为文档不完善而放弃 API。

* IBM 的第三项研究发现，在 API 文档中查找所需信息的平均时间为 20 分钟。

* 参与一项研究的软件工程师表示，他们大约花费 40% 的时间阅读文档。

API 文档的重要性

从开发人员的角度来看，良好的文档可以节省时间。开发人员无需花费数小时来解读和试验 API 的功能，而是可以参考提供清晰说明、示例和故障排除提示的综合文档。这可以节省宝贵的开发时间并加快集成过程，使开发人员可以专注于构建创新应用程序。

此外，有效的 API 文档可以改善 API 提供商和开发人员之间的协作。它充当一种通用语言，促进沟通并确保双方意见一致。开发人员可以轻松了解 API 的预期行为、可用端点和所需参数，从而使他们能够将 API 无缝集成到他们的应用程序中。

谁从 API 文档中受益？

您的API 文档受众是细分的。因此，确定从您的文档中受益的不同人群非常重要。这将让您深入了解如何满足他们的需求。

开发人员

开发人员是直接使用您 API 的人。为了有效地使用您的 API，他们需要了解它如何应用于他们的用例。此外，如果他们需要对 API 运行 QA 测试，他们需要尽可能多的有关 API 的信息。他们可能需要学习如何访问和集成您公开的数十个甚至数百个资源。

研究表明，多年来，开发人员对 API 文档的信心越来越强。随着数字的不断增长，提供与 API 配套的相关技术文档才是明智之举。

管理员和其他人员

这群人可能永远不会真正使用您的 API。他们负责确定团队所需的资源。其中一些人是技术人员，如 CTO，而其他人可能是 COO。确保您的 API 文档在编写时考虑到了这样的受众。

最后，记者、技术爱好者和其他非专业人士可能会看到您的 API 文档。您如何定位他们？针对技术含量最低的受众进行撰写。

API 文档的基本准则

1.定义 API 文档的目的和范围

在深入研究技术细节之前，必须先定义 API 文档的目的和范围。问问自己，文档的目标是什么？你希望开发人员通过阅读文档实现什么目标？确定主要目标并概述你需要涵盖的主题。

考虑目标受众及其需求。他们是需要深入技术信息的开发人员，还是寻求高层次概述的业务用户？相应地调整详细程度和使用的语言。

2. 记录 API 端点

API 端点是 API 的支柱，定义可用的功能和操作。记录每个端点，清晰描述其用途、支持的 HTTP 方法（例如 GET、POST、PUT、DELETE）以及预期的响应格式。

包含 API 请求和响应的示例，以说明预期行为。使用清晰简洁的语言，尽可能避免使用技术术语。考虑使用数据结构或图表来可视化复杂的负载或资源之间的关系。

3.记录参数和请求负载

参数在 API 交互中起着至关重要的作用，允许开发人员自定义其请求并检索特定数据。记录每个参数，包括其名称、数据类型、必需/可选状态以及任何约束或验证规则。

提供清晰的 API 请求构造示例，展示参数的用法。考虑重点介绍可能需要不同参数的常见用例和场景。

对于接受请求负载的 API，请记录负载的结构和格式。指定必填字段、预期数据类型以及任何约束或验证规则。包括有效负载的示例，以指导开发人员准确构建请求。

4.记录身份验证和授权方法

在 API 交互中，安全性至关重要。记录 API 支持的身份验证和授权方法，概述开发人员验证其请求和访问受保护资源所需采取的步骤。

解释不同的身份验证机制，例如 API 密钥、OAuth 或 JWT，并提供有关如何获取和使用必要凭据的明确说明。包括带有身份验证标头或令牌的 API 请求示例，以便更好地理解。

确保开发人员了解与每种身份验证方法相关的授权范围和权限。记录所有确定授予不同用户的访问级别的访问控制规则或角色。

5.提供示例、用例和代码示例

开发人员通常通过实际示例和用例来获得最佳学习效果。提供各种示例来演示如何在各种场景中使用 API。包含带有代码片段的分步说明，以指导开发人员完成常见任务或工作流程。

考虑提供多种编程语言的示例，以满足具有不同背景的开发人员的需求。突出显示任何可简化 API 集成的特定语言库、SDK 或框架。

对于复杂或高级用例，请考虑提供完整的代码示例或参考实现。这些示例可作为开发人员的起点，展示最佳实践和利用 API 的有效方法。

6. 组织和构建您的文档

组织良好的文档对于轻松导航和信息检索至关重要。将信息分为逻辑部分并提供清晰的目录。使用标题、副标题和项目符号来提高可读性和可扫描性。

7. 了解用户的需求

创建 API 文档时最重要的步骤是清楚了解用户的需求以及他们对文档的期望。首先研究 API 的目标受众，并考虑他们的技术知识水平。这可以帮助您设计文档，以最有效的方式满足他们的需求。

8. 瞄准最不专业的受众

当为混合受众写作时，最明智的方法是针对读者中最不了解技术的人。尝试回答基本问题，在必要时给出解释，并减少使用术语。以下是针对非技术受众的一系列方法

讲故事：利用案例并围绕案例讲故事。这可以吸引各种类型的受众，并展示您的产品的实际效果。

详尽：将所有重要信息都写出来很重要，但你应该尽量用最少的文字来表达。写一个大纲，让你把概念分解成简洁的部分。

具有指导意义：让用户知道从哪里开始，从哪里结束。以清晰的步骤详细说明复杂的信息。在必要时提供示例。

9. 指出相关的支持资源

您的读者希望获得尽可能多的帮助。不要吝啬提供信息。指出他们可能需要的任何相关指南和支持资源。不要让他们猜测。支持文档的一些示例如下：

入门指南：这提供了使用 API 的全面方法。目标是确保您的消费者能够成功使用您的产品。

交互式控制台：控制台可帮助您的受众测试您的 API 并实时查看结果。这是一种简单的方法，但能带来巨大的回报。

库：代码库使开发人员能够轻松调用不同的资源。访问不同语言的方法以使用您的 API 有助于开发人员更轻松地使用 API。

10.利用行业标准

让读者轻松理解您的文档；使用熟悉的布局和设计。如果您使用文档生成器，那么布局已经为您决定了。

以下是一些建议：使用良好的对比度：Web 内容可访问性指南 2.1 (WCAG) 建议图形和用户界面组件（如表单输入边框）的对比度至少为 3:1。WCAG AAA 级要求普通文本的对比度至少为 7:1，大文本的对比度至少为 4.5:1。

使用动态布局：如今，布局必须易于添加书签。使用 PDF 和单页文档并不合适。确保您的文档是动态且可扩展的。

导航栏：导航栏应紧贴屏幕。让用户轻松切换页面。

11.详细描述您的请求-响应周期

您的用户不应该对 API 响应感到惊讶。他们应该确切地知道 API 调用会带来什么结果。

记录 API 可能提供的所有与参数和响应相关的调用。响应可作为用户的上下文指南，显示他们是否走在正确的道路上。

响应还会提供错误消息指导。总的来说，这有助于您的用户取得成功。在描述完整的示例响应正文时，请务必涵盖多种格式。

最后，示例很重要。在您的 API 应返回的每个对象中提供示例，以及消费者可为成功 API 调用添加的参数示例。API 可观察性工具可以提供帮助。

12.清楚地解释错误信息

在使用任何 API 时，错误都是不可避免的一部分，因此在文档中清楚地解释错误非常重要。这样，用户就会明白为什么会出现错误，并知道要采取哪些步骤来解决问题。提供常见错误消息的示例也有助于用户在故障排除时参考。务必对每条错误消息提供良好的描述，并解释错误发生的原因。

13.免费提供

相信我，真正让开发人员恼火的一件事就是封闭的 API 文档。不要被愚弄，封闭的文档不会增加转化率。开发人员和决策者在决定使用您的 API 之前想知道会发生什么。

根据需要使用尽可能多的代码示例。开发人员对此非常感激。不要只说不做示例。

最后，针对搜索引擎进行优化。如果无法通过简单的 Google 搜索找到您的文档，那么它们就毫无用处。确保页面已编入索引、标题正确且描述清晰。

14.定期更新你的文档

没有人喜欢过时的文档，请定期更新您的 API 文档。以下是一些建议：

拥有标准的更新流程/框架：将您的文档纳入 API 更新流程。这可确保您在推出新功能时，您的文档也已准备好发布。

经常检查：经常检查文档可以发现过时的地方。安排检查时间可以保持流程的精简。

使用分析：良好的 API 分析将显示最常使用的端点。这将为您的 API 文档审查过程提供信息，帮助您将更新重点放在最常用的部分上。

API 文档中的常见挑战

虽然 API 文档至关重要，但它也存在一些挑战。让我们来探讨一下 API 提供商在创建文档时面临的一些常见障碍以及如何克服这些障碍：

• 取得适当的平衡：主要挑战之一是在技术准确性和用户友好语言之间取得适当的平衡。开发人员需要准确的技术细节，但以易于理解的方式呈现它们可能是一个挑战。为了克服这个问题，请考虑使用清晰简洁的语言，尽可能避免使用行话，并提供相关的示例和解释。
• 维护最新文档：另一个挑战是维护最新文档。API 会随着时间的推移而发展，新功能、端点和参数会被添加或修改。保持文档与 API 本身同步至关重要。定期检查和更新文档以确保准确性和相关性。

原文链接：How to Write API Documentation: 14 Essential Guidelines