新人如何写好 API 文档

什么是 API 文档？

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

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

 

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

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

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

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

我们继续——那什么是 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 文档之旅更轻松。使用工具的好处是这些工具提供的协作功能和标准模板，而不是从头开始。

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

Eoapi

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

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

Postman

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

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

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

DapperDox

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

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

SwaggerHub

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

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

希望这篇文章能帮助到你~