原文：How to Write Good API Documentation，作者：Maybell Obadoni
想象一下，你刚买了一个新的家庭影院系统，你去设置它，首先要做什么？
谢天谢地，你有一本方便的设备手册来帮助你。你只需要按照手册中详细说明的步骤进行操作，然后就可以了。你的家庭影院系统已经准备好播放你喜欢的歌曲了。
就像设备手册如何指导你进行设置和安装一样，API文档可以帮助指导你完成配置API。
什么是API文档？
在深入研究API文档之前，让我简单解释一下什么是API以及它的基本功能。
API是Application Programming Interface（应用编程接口）的首字母缩写。
无论你是初级编码员还是高级开发人员，你都会在你的软件开发旅程中经常遇到这个术语。它是你的计算机、手机或应用程序与外部资源之间的桥梁。
换句话说，API赋予你的软件与其他软件程序、数据库或资源互动的能力。与其为你的应用程序的某一特定功能编写程序，你可以使用具有类似功能的现成的API。
许多API是公共的（免费的），而其他的则是私有的，需要付费购买一个让你访问API的私钥。有不同类型的API，如REST（Representational State Transfer）、SOAP（Simple Object Access Protocol）以及其他。
那么什么是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文档之旅变得更容易。使用工具的好处是这些工具提供的协作功能和标准模板，而不是从头开始。
下面是一些流行的工具及其优点的清单。
Postman
Postman是一个用于构建和维护API的平台，具有创建API文档的功能。
Postman使用其机器可读的文档工具，使API文档过程更容易和更快。你可以免费注册Postman并将其安装在你的PC上。
尽管Postman对其制作的所有API文档自动提供更新，但其用户界面一开始可能难以理解。
DapperDox
DapperDox 是一个开源的API文档工具，提供各种主题来创建你的文档。这个工具结合了图表、规范和其他内容类型，为你提供更好的文档。
它的优点是允许作者用 GitHub 风格的 markdown 编写，但这个工具的更新是不定期的。
SwaggerHub
SwaggerHub 是在许多技术作者中一个流行的API文档工具，因为它是互动的，易于使用。
虽然它对初学者很友好，但除了个人使用外，它需要付费。因此，如果你是一个组织的一部分，想使用SwaggerHub，你的组织将不得不为它付费。
无论你是选择这里列出的工具还是选择其他工具，你都应该考虑以下几点：
- 你将在什么环境下使用该工具？是用于个人使用还是作为组织的一部分？
- 你的技术水平如何？你是初学者还是专家？
- 用户界面和用户体验如何？
一些值得学习的API文档的例子
下面是一些API文档，它们给你开始编写优秀的API文档的灵感。这些文件中的每一个都以简单的步骤和可理解的术语向开发者详细介绍了产品API的用法。
GitHub API Docs
GitHub提供了非常有用的文档。在这里查看他们的API文档：
REST API是开发人员用来访问网络或数据库数据的常用API。Github的这个文档包括概述、指南，甚至是如何在你的程序中使用REST API的代码。
这些文档的有趣之处在于，无论你的技术水平如何，你都可以轻松地理解它。
Paystack API Docs
你是否正在构建一个需要支付的应用程序？Paystack是一个用于支付的金融技术解决方案。他们的团队为开发者提供详细的信息，说明如何在你的程序中使用Paystack的API。这更像是提供一本关于使用API的手册，以避免在将API消耗到你的程序中时出现混乱。
Twitter API Docs
Twitter的API文档解释了开发者如何与App互动。这些文件清楚地详述了不同的部分（用户、推文、直接信息等）和它们的操作。
虽然更多的信息需要权限访问，但你只需点击一下链接，就可以访问基本的信息。
结语
文档阐述了一个工具是如何工作的，以便其他人能够正确使用它。创建API文档并不容易，但创建有用的文档并不像你想象的那么难。
只要记住：从写你的初稿开始，每天改进它，当你遇到困难时，向导师或资深同事寻求帮助。
现在就去写那些将与下一个世界级产品一起使用的API文档吧。