什么是好用的 API 文档

什么是好用的 API 文档

对程序员来说,API 文档是再熟悉不过的东西,几乎每天都要打交道。在大多数开发团队中,只要有前后端的合作,API 文档就会作为两方沟通的桥梁而存在。API 文档是后端对所提供服务的说明,前端开发者通常作为 API 文档的消费者,下面我就从一个消费者的角度谈谈什么样的 API 文档是好用的。

API 文档是什么?

简单来说它就是对所有 API 的调用和其中涉及到的参数的清晰的解释说明。说具体一点,就是每个 API 可以做什么,以及对 API 中每个参数的解释,包括它们的类型、格式、可能的取值、验证规则、是否必需等。

API 文档有什么?

欢迎页面

常常会有人忽略了这个页面的重要性,当然,如果是内部的项目,欢迎页面有时不是那么重要,但 API 文档如果是对外的,例如每个公司的开放平台文档,那么一个内容详尽的欢迎页面甚至可以决定一个开发者是否愿意接入你们的平台。

欢迎页面可以包含的内容有:

  • 产品提供了哪些 API,可以用来做什么
  • API 是如何工作的,技术架构的简单介绍
  • 新手指南,从零开始到建立一个可用的 API 调用过程的步骤,包括建立账户、设置开发环境、鉴权、实际运行等几个方面

Spotify 的 API 文档欢迎页面)

包含完整上下文的示例

设想一下我们读 API 文档的场景,我们会像读小说一样从头开始看吗?大多数情况下并不会,一般我们会从 API 列表里面根据名称直接跳转到我们需要查看的 API 处直接阅读。因此,对于内容的组织,在每个 API 的解释中都要包含所有必需的信息和相关的解释说明。例如 GitHub 的 REST API 文档中的 commits 一节,每个 API 的部分,详细给出了:

  • 返回值,路径规则,参数解释(参数名、类型和描述)
  • 输入参数的示例
  • 返回值的示例
  • 对于一些特别的概念,给出了跳转链接便于查看

示例的常见类型

  • 自动生成的代码示例

通过一些工具可以从项目的代码中直接生成文档示例,例如 api blueprint。这样做的好处是,当修改源码的同时,文档内容也会同步更新,避免了文档更新不及时的问题。不过建议不要完全依赖自动化的工具,在生成内容后还是需要手动补充必要的说明,使得文档内容更加易懂。

  • 示例项目

没有什么比 API 在真实项目中的应用更直观的了,通过真实的示例项目代码,可以帮助用户理解每个 API 是如何使用,如何联系的。通常可以在文档中给出指向示例项目 GitHub 仓库的链接,代码量不大的话,也可以直接贴在文档中。

  • 支持多语言的客户端模块

顾名思义,这种方式是将 API 的调用,包括鉴权、配置等过程都封装在客户端模块中,用户直接在项目中引用并调用封装好的方法即可。这种方式能简化客户端调用 API 的工作复杂度,但同时会增加 API 提供者的工作量,在更新后端服务的同时客户端模块也需要同步更新。例如 GitHub 就为不同语言提供了客户端模块。

错误相关信息

另外,在调试过程中一旦出现错误,关于错误信息的详细文档可以减少解决错误的难度,其中应该包含:

  • 错误的状态码以及描述
  • 引起错误的原因
  • 如何解决错误

事实上,能做到这一点的文档就会少很多了,GitHub 的 API 文档在这方面做的比较一般,Context.IO 的文档 在错误信息上表现比较好,可以作为一个参考。

与全局内容相关的主题

这里指的是对任何 API 文档都通用且必需的内容,包括:

  • 快速入门指南和教程
  • 权限认证相关信息
  • HTTP 请求方式和错误处理

至于这些部分的内容会根据不同的后端服务而有差异,同时,在每个具体的 API 解释中,出现与这些内容相关的概念时,可以给出具体章节的链接,便于开发者随时跳转查看。

一些可用性建议

API 文档可以提供一些小功能来提升用户的体验。例如在代码示例旁设置复制代码的按钮,方便用户一键复制代码;为调用 API 的代码示例提供多语言支持,用户可以查看不同语言调用 API 的示例,配合复制功能,可以减少书写重复代码的工作量。

API 文档长什么样?

一个好的 API 文档,除了内容合理详细之外,它的样式和交互方式也要简单易用。现在的 API 文档基本基于网页来展现,利用网页的显示特性,有一些比较常见的设计方式。在这里推荐一些适合作为 API 文档展现要素的一些最佳实践。

  • 单页形式

只要 API 文档不是特别庞大,都推荐用单页形式展现,在单个页面中查找任何内容(无论是用浏览器的网页搜索还是用文档提供的导航),速度都会很快,再加上设置在页面中的锚点,分享某条 API 记录的位置也很方便。当然,如果 API 文档内容过多,强行放在单页面中会影响页面体验,就应该果断对文档进行拆分,但要记得在每个子页面中保留全局的导航信息,方便用户在各个页面进行跳转。

  • 固定导航栏

使用 API 文档的过程中,由于需要频繁查找内容,固定在页面中的导航栏显得十分必要,用户可以随时通过导航栏查找文档的内容。

  • 多列布局

既然用了固定位置的导航栏,同时使用多列布局的形式也很顺理成章。在宽屏的桌面端网页上,多列布局可以很好的组织文档的内容,导航、API 说明、代码示例可以各占一列。

API 文档的维护

维护 API 文档应该像维护一个独立项目一样,每次更新都通过拉取分支的形式,编辑者在检查了文档内容的正确性简洁性后,由项目成员进行 review。

在 API 文档发布后,后期维护同样重要。主要有两个方面的内容:

  1. 新功能和废弃功能。在发布新功能之前应先发布文档,并保证文档经过了标准的 review 流程。对于废弃掉的旧功能,应从文档中移除,同时建议在相应的位置给出废弃功能的提示和升级指南,方便使用旧功能的开发者进行升级工作。
  2. 在文档页面上应该预留文档的 contribute 入口,如果文档托管在 GitHub 这样的平台上就提供指向仓库的链接,方便每个阅读文档的用户给文档提 Issue 或者 PR。如果文档是闭源的,也应该至少留有提供反馈信息的位置。

以上是对项目开发合作中写出友好的 API 文档的一些想法和建议,欢迎讨论。

编辑于 2018-05-14

文章被以下专栏收录