如何编写高质量 API 文档

想象一下，你刚买了一个新的家庭影院系统，然后你去设置它。你先做什么？

谢天谢地，你有一本指导说明的手册来帮助你。你只需要按照手册中详述的步骤进行操作，瞧！你的家庭影院系统已准备好播放你最喜爱的歌曲。

就像指导手册如何指导你完成设置和安装一样，API 文档可以帮助指导你配置 API。

什么是 API 文档？

在深入研究 API 文档之前，让我简要解释一下 API 是什么以及它的基本功能。

API 是应用程序编程接口的首字母缩写。

通过 API 将设备连接到数据库

无论你是初学者还是高级开发人员，你都会在软件开发过程中经常遇到这个术语。它是你的计算机、手机或应用程序与外部资源之间的桥梁。

换句话说，API 使你的软件能够与其他软件程序、数据库或资源进行交互。无需为应用程序的特定功能编写程序，你可以使用具有类似功能的现成 API。

许多 API 是公共的（免费），而其他 API 是私有的，并且需要支付私钥才能访问 API。有不同类型的 API，例如 REST（具象状态传输）、SOAP（简单对象访问协议）等。

我们继续——那什么是 API 文档？好吧，它是一份书面指南，说明了 API 的功能、如何将其集成到你的程序中、API 的用例以及示例。

请记住，API 文档是技术内容。这意味着它将包含一些技术术语，但仍应可读且易于理解。

谁来编写 API 文档？

API 由软件开发人员构建。由于软件开发人员直接参与构建和使用 API，因此他们更容易创建文档。

软件开发人员编写 API 文档的缺点是他们从非常技术性的角度编写，这会使文档很难理解。另一个问题是 API 开发人员在开发 API 的同时创建文档需要更多时间。

因此，一个不错的选择是将 API 文档的任务分配给技术作者。技术作者是将内容写作的专业知识和技术知识相结合，以制作不仅具有技术性，而且内容丰富且易于理解的文档的人。

技术作者从 API 开发人员那里了解 API，然后创建教程、示例和其他用于文档目的的内容。

同时，API 开发人员会监督技术编写者，以确保编写的文档准确无误，并在必要时向编写者提供更多信息。

我们的目标是让每个人共同努力，制作出能够充分解释 API 并指导用户不混淆的文档。

如果你有兴趣为 API 编写文档，但不知道从哪里开始或如何开始，本文将帮助你开始。

如何开始编写 API 文档

在编写 API 文档时，首先要创建几个大纲。这将使你对你打算写的内容有一个概述。

接下来是为你创建的每个大纲填充信息。这可以通过从 API 开发人员那里获取 API 描述、使用的语言、其他参考和示例案例来实现。你还可以查看 API 的现场演示，以便亲身体验它的工作原理。

最后，结合你填充的信息并按逻辑顺序排列它们。

请记住在公开文档之前，校对你的文档并与 API 开发人员交流讨论看看有什么需要更改的。

既然你知道从哪里开始，那你如何把这些内容放在一起，使它们成为一个有意义的整体？

API 文档中包含的内容

1. 概述

这类似于项目报告的摘要页面。

概述应包含 API 及其正在解决的问题的摘要。它还可能包括使用此特定 API 优于其他类似 API 的好处。

2. 教程

这是文档的主要部分。

它应该包括你用来向用户解释 API 概念的不同内容格式。它还可以包括参考链接以及集成和使用API的分步指南，以便它能够正常工作。

3. 例子

一旦你解释了 API 的工作原理和/或提供了详细的步骤，最好展示调用、响应、错误处理和其他关于开发人员如何与 API 交互有关的操作的示例。

4. 词汇表

虽然这是可选的，但我建议为你的 API 文档添加词汇表页面。

为了避免长文本块让用户感到厌烦，你在整个文档中使用的各种术语、模式、图像等的解释都可以放到词汇表中。然后你可以在文档中引用这些内容，并链接到词汇表。

如何编写有用的 API 文档

了解 API

正如我们刚刚讨论的那样，你应该对正在记录的 API 有第一手的了解。请记住，你的目标是指导可能对 API 一无所知的潜在用户。

如果你对产品的架构、功能和其他重要信息有深入的了解，你将能够有效地编写 API 的产品描述部分，而无需进行任何猜测。

如果你对正在编写的 API 没有充分了解或完全相信，请花一些时间进行研究并尽可能多地收集信息。自己使用 API，以便深入了解它的工作原理。

使用相关内容

API 文档不仅限于书面指南。你可以使用短视频或 PPT 来说明 API 的集成。

在编写文档时说明不同的用例。这将帮助读者识别哪一个与他们的相似，或者找到他们可以轻松关联的一个。

此外，在你认为必要的地方和时间包括一些代码片段。这将使读者可以在阅读文档时跟进。正如流行的谚语所说，“告诉我，我会忘记。教我，我会记住。让我参与，我会学习。”

足够清晰

API 是软件或硬件的指南，因此你在编写文档时需要使用一些技术术语。如果你想成为一名专业的技术作者，请一定要坚持。

一份好的文档不是具有复杂语法结构的文档，而是具有相关性、直接性和清晰性的文档。只有用简单易懂的语言编写时，它才能具有相关性。

你的 API 文档应尽可能采用最简单的形式，但不应遗漏任何重要细节。此外，请确保在第一次使用它们时解释首字母缩略词和技术术语，或者将它们放在文档末尾的词汇表中。

列举指南

如果内容是逐项列出的，则文档更容易理解。这是写得简洁的主要原因。

逐步对指南进行编号或逐项列出有助于用户弄清楚在每个时间点要做什么。这类似于从 A 到 Z 阅读字母表。

通过明确的步骤，用户在遇到错误时可以轻松返回。

检查错误

每次阅读文档时，总会有一些内容需要更改、更新甚至删除。这是作者们经常会遇到的经历，这很正常的。

黄金在提炼之前要经过几道熔炉。这么说吧，你的文档应该经历一个相似的过程(而不是一个炽热的熔炉)，这样它就会成为一个准备充分的文档。

彻底的审查过程可以帮助你最大限度地减少任何错误并完成清晰明了的文档。

API 文档的最佳工具

编写 API 文档可能非常耗时且难以维护。但是一个好的文档工具可以缓解大部分（如果不是全部）这些问题。

有许多工具可以让你的 API 文档之旅更轻松。使用工具的好处是这些工具提供的协作功能和标准模板，而不是从头开始。

下面列出了一些流行的工具及其优势。

1、Eoapi

Eoapi 是一款类 Postman 的开源 API 工具，它更轻量，同时可拓展。

支持API有关的核心功能，还可以通过插件市场帮助你将API发布到各个应用平台，比如发布到网关成API 上线，或者和低代码平台结合，将API 快速变成可使用的组件等。

2、Postman

Postman是一个用于构建和维护 API 的平台，具有创建 API 文档的功能。

Postman 使用其机器可读的文档工具来简化 API 文档过程。你可以免费注册 Postman 并将其安装在你的 PC 上。

尽管 Postman 为其自动生成的所有 API 文档提供更新，但它的 UI 一开始可能难以理解。

3、DapperDox

DapperDox是一个开源 API 文档工具，它提供了用于创建文档的各种主题。该工具结合了图表、规范和其他内容类型，为你提供更好的文档。

它的优点是允许作者使用 GitHub 风格的 markdown 进行编写，但此工具的更新是不定期的。

4、SwaggerHub

SwaggerHub是许多技术作家的流行 API 文档工具，因为它具有交互性且易于使用。

虽然它对初学者很友好，但它需要为个人使用以外的任何东西付费。因此，如果你是某个组织的一员并且想要使用 SwaggerHub，则你的组织必须为此付费。

无论你是选择此处列出的工具还是其他工具，你都应考虑以下事项：

• 你将在什么环境中使用该工具？它是供个人使用还是作为组织的一部分？
• 你的技术水平如何？你是初学者还是专家？
• 用户界面和用户体验如何？

API Docs 的一些很棒的例子

以下是一些 API 文档，它们将激励你开始编写出色的 API 文档。这些文档中的每一个都以简单的步骤和易于理解的术语向开发人员详细介绍了产品 API 的使用。

1、GitHub API 文档

GitHub 提供了非常有用的文档——这不足为奇。在这里查看他们的 API 文档：

REST API 入门 - GitHub Docs

REST API 是开发人员用来访问来自网络或数据库的数据的流行 API。Github 的这个文档包括概述、指南，甚至是关于如何在你的程序中使用 REST API 的代码。

这些文档的有趣之处在于，无论你的技能水平如何，你都可以轻松理解它。

2、Twitter API 文档

Twitter API 文档解释了开发人员如何与应用程序交互。这些文件清楚得详细说明了不同的部分（用户、推文、直接消息等）及其操作。

Twitter API 支持文档

结论

文档展示了工具是如何工作的，以便其他人可以正确使用它。API 文档并不总是容易创建的，但是创建有用的文档并不像你想象的那样困难。

请记住：从写你的初稿开始，每天改进它，当你遇到困难时寻求导师或资深同事的帮助。

现在继续编写将随下一个世界级产品一起发布API文档。

关于我们

Eoapi 是一款类 Postman 的开源 API 工具，它更轻量，同时可拓展。

项目地址：

https://github.com/eolinker/e...

官网地址：

https://www.eoapi.io/?utm_sou...

如果你对于 Eoapi 有任何疑问或者建议，都可以去 Github 或者来这里找我，等你噢。