API文档质量检查清单

你知道什么是API，特别是Baklib可以帮助你了解的REST API。

这里，我们将讨论REST API。

有多种工具可以帮助自动化开发文档，例如Postman或Swagger。但你仍然需要“充实”生成的文档，使其既有用又可读。

REST 开发文档通常分为两个主要部分：

1. 介绍部分，例如包括：

• API的用途
• 任何先决条件，如设置注意事项（包括API密钥要求）
• 要使用的基础URL
• 对于输出量大的API的分页考虑
• 结果代码（最常见的是200 – 成功和40x – 各种类型的错误）

2. API本身。

API可能被分成几个主要的功能组，每个组都有自己的端点和调用（GET、POST、PUT、PATCH、DELETE等）。

每个调用通常需要两个表格，一个解释查询参数，另一个说明结果。请求参数可以直接输入，也可以通过输入JSON文件输入。它们在第一个表格中描述。结果通常出现在一个JSON文件中，其字段在第二个表格中描述。

在请求/结果部分之后，添加一个返回代码部分。始终显示200和400返回代码。如果其他可能的返回代码是标准的，那么交叉引用“常见返回代码”即可。如果使用特定于调用的返回代码，请在此处添加。

最后，提供一个示例。许多现代的开发文档页面右侧都有一个垂直栏，展示了多种格式（如cURL、PHP、JavaScript等）的API调用示例。其他可能的形式包括API描述下方的水平代码栏，或者一个指向API沙盒的链接。如果由于某些原因，这些功能不可用，那么至少应该添加一个包含硬编码示例的文本框。 这里还有一定的灵活性：一个仅包含单个简单参数的调用显然不需要第一个表格。同样，对于POST和PUT调用，通常也不需要第二个表格。

看看这些开发文档示例：

Twitter API

Source

Dropbox API

Source

YouTube API

Source

开发文档 – 深入探讨

REST API调用的剖析

一个REST API调用主要由四个部分组成：

• 一个指令（或动词），例如GET、POST、PUT、PATCH、DELETE等。
• 一个服务器URL，例如https://some.server.com
• 一个端点（或路径），例如/data/of/interest
• 一个请求，跟在端点后面，例如?zip=12345&units=metric

一个完整的调用看起来会像这样：

GET https://some.server.com//data/of/interest?zip=12345&units=metric

您几乎不需要以这种形式编写或记录API调用。市面上有多种GUI工具，允许您以表单形式输入API调用的各个组件。它们会自动生成API调用，并提供可执行该调用的示例代码片段（如Python、JavaScript、C++等）。例如，您可以了解以下工具：

• Postman
• Swagger
• Stoplight

其中一些工具还能为您的API生成文档页面。如果您习惯使用命令行，可以了解一下curl命令（即cURL）。该工具在所有主流操作系统（Windows、Unix、Linux、MacOS）上均可使用。大多数开发文档工具在生成代码片段的同时，也会生成相应的curl命令。

输入

为了避免提供冗长的请求参数列表，像Swagger这样的工具可以帮助您将请求参数编码成JSON或YAML文件，作为请求的输入。

JSON编码应遵循OpenAPI规范，该规范标准化了API调用的方式（另请参阅《OpenAPI规范详解》）。遵循OpenAPI规范，可以像上文提到的那样，实现基线文档的自动生成。

OpenAPI标准并未规定日期时间等详细的数据字段格式。这些格式通常由API的编程上下文决定。例如，JavaScript有一个Date类，用于规定日期和时间的格式。

提示：API开发者应规定所有输入数据的格式。

💛🧡🧡客户评价：我们的IT团队需要一个存储库进行知识管理，以便我们的团队知识可以传承下去。在此外，我们正在寻找一种解决方案，使我们能够提供为我们的团队成员提供自助服务。Baklib提供了一个易于部署的低成本的解决方案，超出了我们的预期。优秀的知识管理平台。

API调用的输出可能非常独特，不过现在的趋势是提供JSON格式的输出。所需的输出细节也在输入JSON文件中作为字段指定。输出可能很长，可能需要通过连续的API调用进行分页。这里有一个网站这样做：Webz.io API。

最重要的返回状态码是200（成功）和4xx（某种错误）。完整的返回状态码列表可以在这里查看：HTTP状态码。请与API开发人员核实，以确保这些代码是以标准方式使用的。

想象一下，您需要反复获取数据——比如每小时一次的天气报告或短消息，就像WhatsApp或Twitter那样。一种方法是将GET请求放入一个无限循环中。这是一种糟糕的编程方式。现代的解决方案是使用webhook（或回调），使服务器能够在数据可用时将数据推送给您。服务器向您的浏览器发送异步POST请求。例如，请参见：什么是webhook？

• 开发人员找不到他们想要的内容，从而感到沮丧！
• 开发人员找到了他们想要的内容，但细节不足。

糟糕的文档可能被以下问题困扰——

• 示例不足或缺失。
• 没有用例。

所有这些将导致——

• 新用户上手缓慢
• 过多的支持工单（好吧，至少看看Jira API参考！）
• 客户流失（最糟糕的情况）。

确保开发文档质量

查找内容

假设我们在API所有者的网站上，您如何搜索所需的API？这次，Google不是答案。

关键是为每篇API文章正确设置元数据。使用设置>SEO字段：

如果添加了足够且突出的关键词，API用户应该能够在主窗口的搜索栏中一次性找到所需内容。

准确性和完整性

在准备开发文档期间，运行每个API以确认其行为与文档所述完全一致。同时确保没有“遗漏的部分”：您可以假设API用户是称职的工程师，但不要假设他能“领会言外之意”。宁可过于明确，也不要含糊不清。

可读性

文本

您的任务是启发读者——而不是让他们昏昏欲睡。因此：在需要文本的地方，避免冗长的跨屏幕段落。务必使用简短有力的句子。

表格

表格在开发文档中无处不在。你需要仔细考虑表格的布局。由于开发文档大多是在线的，因此可以制作非常长的表格。

在记录JSON文件输出字段时就会出现这种情况。如果可能，请“冻结”表格的标题行（可能还包括左侧列），就像在Excel或Google Sheets中那样。

有些用户需要PDF文档：对于他们，请尽量确保表格在屏幕上不会过宽，以便在PDF中看起来合理。

简洁性

保持简洁——但不能以牺牲准确性和完整性为代价。过度追求简洁可能会冒犯到有能力的工程师。

优秀的用例参考

优秀的用例参考是API的展示柜。如果API是新的，还没有任何用例，那么你就需要用更多的例子来弥补。在这里，一个API沙盒是必不可少的。

附加参考资料

关于API及其使用背景信息的附加参考资料会很有帮助。

了解更多：REST vs. SOAP：有什么区别？