译者 | 陈峻
审校 | 重楼
不知您是否注意到，编写应用程序接口（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文档的介绍部分写得内容丰满。
如前所述，介绍部分是开发人员与该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'])4.使用一致的命名规则
命名规则的一致性可以提高文档的可读性。通过对端点、参数和响应采用清晰统一的术语，可以避免不必要的混淆，毕竟不一致性往往会导致误解和错误的产生。此外，保持标准化的命名方法，可以为开发人员创造更顺畅的学习体验，使他们能够更容易地将您的API集成到自己的项目中。例如：请不要交替使用“temp”、“temperature”、以及“temp_data”，而需要在整个文档中统一为“temperature”的术语。
5.包括请求和响应示例
开发人员需要根据有关预期输入参数和API响应结构的相关记录，来了解应如何格式化请求，并解析API返回的数据。因此，我们需要为请求和响应提供现实的示例，以弥合理论解释和实际执行之间的差距，让开发人员无障碍地使用您的API。下面是一个典型的请求示例代码：
// 请求示例
JSON
{
"city": "New York",
"units": "metric"
}
// Response Example
{
"Temperature": 23,
"condition": "Clear",
"humidity": 50
}6.错误处理信息
由于清晰的错误处理信息更利于排障，因此我们需要在文档中体现潜在的错误代码、信息及其含义，以确保能够指导开发人员该如何处理这些错误。这种积极主动的方式，不仅能够帮助开发人员迅速解决问题，还可以减少他们的挫败感与困惑，进而带来积极的用户体验。例如：一旦发现被提交的请求中没有需要必填的参数，API则应给出诸如“缺少必填参数：城市”等明确的错误信息。
7.添加限速信息
文档中应体现与API相关的任何速率限制信息，以协助开发人员有效管理API的使用情况，进而避免因速率限制问题而造成的服务中断。此外，文档还应包含检查API的当前使用情况和处理限速的错误详细信息，以帮助开发人员优化应用本身的性能，并确保其能够与该API进行更顺畅的集成。例如：“我们的API速率限制为：每小时100个请求。如果超过此限制，您将收到‘429过多请求’的状态代码。若要检查您的使用情况，请在响应中包含‘X-Rate-Limit-Remaining’标头”。
8.保持更新
定期更新文档可以方便开发人员了解API的相关变更、新增功能、以及废弃了的功能。因此，通过文档来传递版本信息、维护更新日志、以及突出修改的内容，都将有助于在用户群中培养一种针对API可靠性的信任感，特别是在您能够主动更新文档的情况下。例如，在发布说明中，您可以提及：“2.0版引入了新的端点‘/forecast’，可用于扩展天气预测”。
9.鼓励反馈
文档中应鼓励开发人员分享经验、提出问题与建议。这种双向交流将有助于您及时解决潜在的问题，更好地了解用户需求，从而不断改进API的功能及其文档。例如：“我们非常重视您的反馈意见！如果您有任何疑问、建议或遇到任何问题，请联系我们的支持团队：support@xyz.com”。
10.避免含糊不清和假设
清楚地阐明您的指令，避免对用户已有的知识做出假设。请记住，模棱两可或含糊不清的文档只会导致误解和实施错误。只有清晰的解释，才能确保那些经验有限的开发人员，也能自信地遵循您的文档。例如，请不要简单地使用一句“只需请求我们的API即可”，而需详细地说明：“请向‘https://api.weathernow.com/current’发送HTTP GET请求，以检索当前的天气信息。”
11.不要过多地使用技术术语
专业术语虽然表达准确，但是也会妨碍用户的理解。为了在准确性和易读性之间取得平衡，最好的一种办法是：在必要时，对技术术语进行定义和解释，让开发人员在理解文档时不会产生歧义或是感到突兀。例如：将“利用异步通信范式提高可扩展性”的措辞改为“允许同时处理多个请求，进而提高性能”。
12.避免长篇大论
密集冗长的段落会让人缺乏继续阅读的耐性，进而导致重要细节被忽略。对此，请确保使用要点、列表、短句、以及标题等分段格式，来有效地组织内容，从而在提高文档可读性的基础上，方便用户在文档中快速找到所需的信息。例如：
- 使用HTTPS进行安全通信。
- 在“授权”标头中包含API密钥。
- 在“接受”标头中指定所需的输出格式。
小结
综上所述，有效编写API文档是一个多层次的过程。它既需要深入了解受众，又需要提供清晰的介绍，实用的代码示例、鼓励用户反馈，并致力于不断的改进。相信通过遵循上述介绍的步骤和实践，您也可以创建出让开发人员倍感实用，并使其能够与API无缝集成的优秀说明文档。
译者介绍
陈峻（Julian Chen），51CTO社区编辑，具有十多年的IT项目实施经验，善于对内外部资源与风险实施管控，专注传播网络与信息安全知识与经验。
原文标题：How to Write API Documentation: Best Practices and Examples，作者：Toluwani Folayan
