共计 3702 个字符，预计需要花费 10 分钟才能阅读完成。
设想一下，你刚买了一个新的家庭影院零碎，而后你去设置它。你先做什么？
谢天谢地，你有一本领导阐明的手册来帮忙你。你只须要依照手册中详述的步骤进行操作，瞧！你的家庭影院零碎已筹备好播放你最青睐的歌曲。
就像领导手册如何领导你实现设置和装置一样，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 或者来这里找我，等你噢。
