译者 | 陈峻

审校 | 重楼

不知您是否注意到，编写应用程序接口（API）文档是每个开发人员的一项重要基本技能。想象一下，用户拿到了一款好评如潮的新设备，却看不懂配套的说明书，他该如何有效地去使用呢？API也是同理：如果没有适当的文档作为指南，提供如何使用其服务的基本信息，那么使用它的开发人员就可能不知所措。因此，就像一本精心编写的设备说明书一样，优秀的API文档应当包括：代码示例、教程以及有关函数、类和返回类型等详细信息。作为一种全面的资源，它将能够为开发人员提供无缝集成和有效调用的所需信息。

在本文中，我们将以创建出色的API文档为目标，指导您使用简单的语言，提供实用的示例，以确保开发人员能够轻松理解和应用这些信息，进而简化他们的集成过程。

什么是API文档？

API是应用程序编程接口（Application Programming Interface）的缩写，是不同软件应用程序之间相互通信的桥梁。其文档提供了与特定API集成和协作的重要指南。从根本上说，API文档是一套指导开发人员和其他利益相关者利用应用程序接口、及其服务，进行无缝交互，实现特定目标的指南。它就像一本全面的手册，为如何有效地与API进行交互，利用其功能，实现预期结果等，提供了清晰的指导。

此类文档提供了包括：请求结构、预期响应、错误消息处理、以及其他基本功能等各方面的详细信息。因此，它为开发人员提供了成功将应用程序接口纳入其项目，并充分利用其功能，所需要获悉的知识和指导。

简单地说，API使得开发人员能够全面利用成熟的平台功能，而无需重新“发明轮子”。例如，Twitter和GitHub等主要平台都提供了各自的应用程序接口，以便开发人员将其所需的功能，无缝地整合到自己的应用程序中。这不仅节省了他们的时间和精力，还促进了开发社区内的协作和创新，毕竟开发人员可以更加专注于构建应用程序的独特方面，而不必从头开始创建某些通用功能。

API文档的类型

1.内部应用程序接口（面向团队）

内部API专为在公司内部网络中的使用场景而设计。它有效地促进了不同团队和系统之间高效的数据交换，也简化了组织内部的沟通。注意，在该场景下，内部开发人员是主要用户，需要实现无缝的协作和信息流的交互。

2. 合作伙伴应用程序接口（针对合作伙伴）

合作伙伴API将访问权限扩展到了组织之外，不过仅与那些可信赖的业务合作伙伴共享。这些应用程序接口会通过更高的安全措施，来限制授权客户的访问。在该场景下，其重点是保持安全的业务关系，并实现对特定功能的受控式外部访问。

3.终端用户应用程序接口（面向终端用户）

最终用户API也称为开放式API，即：没有严格的限制，任何开发人员都可以访问到。这种API文档的主要目的是鼓励广泛的采用，因此其认证和授权措施通常较为宽松。这也是为什么此类API的提供者通常会以广泛的开发者参与为目标，有时甚至会根据API的调用量，提供分级订阅式的访问收费标准。这种在开发和使用上的开放性和灵活性，也是持续支持其营收的一种策略。

谁来编写API文档？

作为应用程序接口的设计者，开发人员会发现自己经常需要扮演记录其创造成果的角色。毕竟他们对于自己开发的API所涉及到的错综复杂的技术知识，最为了如指掌。然而，潜在的缺点也随之出现了，正是因为这种密切的联系，往往会导致技术文档过于专业，可能缺乏以更为友好的方法，让广泛的用户对其理解和使用。此外，将主要精力放在开发和维护API上，有时也会导致文档的优先级被放置到了次要位置。

因此，许多公司选择了另一种方法，来应对该挑战，即：让专业技术撰写人员参与到文档编制的过程中。这些人员拥有将技术理解与创新能力相结合的技能。他们的职责是在API的技术方面，为后续将使用该接口的开发人员，量身定制出清晰的内容“图谱”。

当然，这离不开上述两种角色的密切合作。也就是说，应用程序接口开发人员需要通过向技术撰写人员提供准确的、接口所需的信息记录，并按需澄清某些细节上的缺失，以确保合作所产生的文档具有全面性和连贯性。最终，这份精心制作的文档会在技术深度和易读性之间取得平衡，为目标受众提供清晰且有价值的资源。

API文档应包括哪些内容

1.概述

API文档的基础部分通常称为概述。作为对API的简要介绍，它总结了应用程序接口的目的，概述了其独特的“卖点”。同时，它也可以强调该API在选用上的优势，以及能够为潜在用户提供哪些有价值的见解。例如，在天气类API的文档中，其概述需要简明扼要地指出：“本API可以提供全球各地的实时天气数据，可准确地预报或提供历史气候信息。”

2.教程

作为文档的核心部分，教程在向用户介绍API的概念、以及实际用法方面，发挥着核心作用。其包含的循序渐进的指南，旨在帮助用户清楚地了解具体的集成过程，并展示适当的功能和使用场景。

3.认证

身份验证详细说明了API提供方如何确保开发人员和最终用户的数据安全。鉴于可能存在多种身份验证方法，文档应阐明其中的每一种方法，以便用户全面了解如何安全地访问该API。例如，在社交媒体类API的文档中，身份验证细节可以向开发人员解释如何安全地获取访问其令牌。例如：“要访问用户数据，开发人员必须通过注册应用程序，并按照既定的身份验证流程获取OAuth 2.0访问令牌。”

4.端点定义

API的端点定义，可以精确地定位应用程序接口与软件程序连接的位置。在描述这个被称为端点的交互点时，文档会包含服务器的URL或者是服务等详细信息，从而明确API与其他系统的接口方式。例如：对于消息类API而言，文档会将端点指定为“https://api.messaging.com”，以说明服务器的位置，进而方便开发人员与消息服务进行交互。

5.状态和错误代码

状态和错误代码对于开发人员了解API是否能够按照预期运行，是至关重要的。它包括了对于不同状态或错误情形的描述，以及开发人员该如何查找和解决遇到的问题的相关说明。例如，在文件存储类API的文档中，状态和错误代码可能包括：成功上传文件的“200 OK”、以及试图访问不存在文件的“404 Not Found”。通常，每段代码都会附有相应的说明和解决方法。

6.举例说明

一旦用户掌握了API的内部工作原理，提供示例就显得水到渠成了。示例能够展示成功的API调用、响应、错误处理程序和其他常见操作。这种实用的示例可以增强用户对API的理解，并帮助用户有效地应用API。例如，针对以构造地图类API为基础的应用，示例可以将成功调用展示为“GET /maps/location?lat=37.7749&long=-122.4194”，并返回详细的位置数据。而错误示例则可以展示失败的验证尝试，并指导开发人员该如何正确地处理错误。

7.术语表

术语表可以通过提供技术术语、模式和其他专业术语的简明定义，来简化开发者对于文档的理解。这种方法既能够确保文档的清晰度，又不会给用户带来不必要的复杂技术问题。例如，在机器学习类API的文档中，“模型训练”等术语需要被链接到术语表的相应位置，进而提供简明的解释--“模型训练是使用标注数据指导算法，以提高其预测准确性的过程。”

编写优秀的API文档的实践

1.了解您的受众

了解受众是创建有效API文档的基础。我们应尽量避免假定受众具有统一的专业知识水平，而需要充分考虑到初学者和经验丰富的开发人员，在背景和技能水平上的差异，进而通过文档定制化，来满足他们的特定需求，真正为其所用。例如，对于初学开发者而言，请提供清晰的解释和代码示例，并尽量使用“读取数据”之类直白的语言，而不是“执行GET请求”这样的专业术语。

2.撰写好介绍

作为给开发人员的“见面礼”，下面我们来讨论如何将API文档的介绍部分写得内容丰满。

1. 明确说明目的在本节中，请说明API的主要用途，以便开发人员通过集成您的API实现其开发目标。因此，请确保陈述简洁明了，避免模棱两可。
2. 设定预期概述开发人员能够从该文档获取的内容。即，文档是否包括：详细指南、用例、故障排除技巧，以及针对不同开发人员的特定部分。设定好明确的预期，将有助于用户有目的地浏览和使用文档。
3. 避免使用过于专业的术语

如前所述，介绍部分是开发人员与该API的第一次互动，因此要力求清晰易懂，给受众留下积极的初始体验。

下面，让我们来看某个API的介绍示例：

## 介绍范例

欢迎访问XYZ的API文档！无论您是经验丰富的开发人员，还是刚刚开始编码之旅的新手，本文档都可以成为您了解和使用XYZ API强大功能的入口。

**XYZ API的目的：**

XYZ API被设计为[此处可明确说明主要目的或功能]。它旨在[此处可说明能够解决的特定问题或提供哪些服务]。

**使用本文档的预期：**

在本文档中，您将能找到全面的指南、示例和参考资料，可帮助您将XYZ API集成到自己的项目中。无论您是在查找[此处可填特定用例]，还是在[此处可填常见问题]方面需要帮助，本文档都能为您提供线索。

**谁需要阅读本文档：**

本文档适合[此处可填目标受众]。无论您是前端开发员、数据科学家、还是API爱好者，您都能够在此找到有价值的信息，以增强XYZ API的使用体验。

3.提供代码样本

开发人员通常会依靠各种示例，来了解如何有效地与API进行交互。因此，在展示代码片段时，我们应确保其简明扼要、注释清晰。这将有助于用户，尤其是那些对技术不太熟悉的用户，更容易地掌握API的功能。下面是一个Python示例：

# Python 示例
Python
import requests
url = "https://api.weathernow.com/current"
response = requests.get(URL)
data = response.json()
print("Current temperature:", data['temperature'])