设想一下我们读 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 文档的过程中,由于需要频繁查找内容,固定在页面中的导航栏显得十分必要,用户可以随时通过导航栏查找文档的内容。