译者 | 陈峻
审校 | 重楼
不知您是否注意到，编写应用程序接口（API）文档是每个开发人员的一项重要基本技能。想象一下，用户拿到了一款好评如潮的新设备，却看不懂配套的说明书，他该如何有效地去使用呢？API也是同理：如果没有适当的文档作为指南，提供如何使用其服务的基本信息，那么使用它的开发人员就可能不知所措。因此，就像一本精心编写的设备说明书一样，优秀的API文档应当包括：代码示例、教程以及有关函数、类和返回类型等详细信息。作为一种全面的资源，它将能够为开发人员提供无缝集成和有效调用的所需信息。
在本文中，我们将以创建出色的API文档为目标，指导您使用简单的语言，提供实用的示例，以确保开发人员能够轻松理解和应用这些信息，进而简化他们的集成过程。
API是应用程序编程接口（Application Programming Interface）的缩写，是不同软件应用程序之间相互通信的桥梁。其文档提供了与特定API集成和协作的重要指南。从根本上说，API文档是一套指导开发人员和其他利益相关者利用应用程序接口、及其服务，进行无缝交互，实现特定目标的指南。它就像一本全面的手册，为如何有效地与API进行交互，利用其功能，实现预期结果等，提供了清晰的指导。
此类文档提供了包括：请求结构、预期响应、错误消息处理、以及其他基本功能等各方面的详细信息。因此，它为开发人员提供了成功将应用程序接口纳入其项目，并充分利用其功能，所需要获悉的知识和指导。
简单地说，API使得开发人员能够全面利用成熟的平台功能，而无需重新“发明轮子”。例如，Twitter和GitHub等主要平台都提供了各自的应用程序接口，以便开发人员将其所需的功能，无缝地整合到自己的应用程序中。这不仅节省了他们的时间和精力，还促进了开发社区内的协作和创新，毕竟开发人员可以更加专注于构建应用程序的独特方面，而不必从头开始创建某些通用功能。
内部API专为在公司内部网络中的使用场景而设计。它有效地促进了不同团队和系统之间高效的数据交换，也简化了组织内部的沟通。注意，在该场景下，内部开发人员是主要用户，需要实现无缝的协作和信息流的交互。
合作伙伴API将访问权限扩展到了组织之外，不过仅与那些可信赖的业务合作伙伴共享。这些应用程序接口会通过更高的安全措施，来限制授权客户的访问。在该场景下，其重点是保持安全的业务关系，并实现对特定功能的受控式外部访问。
最终用户API也称为开放式API，即：没有严格的限制，任何开发人员都可以访问到。这种API文档的主要目的是鼓励广泛的采用，因此其认证和授权措施通常较为宽松。这也是为什么此类API的提供者通常会以广泛的开发者参与为目标，有时甚至会根据API的调用量，提供分级订阅式的访问收费标准。这种在开发和使用上的开放性和灵活性，也是持续支持其营收的一种策略。
作为应用程序接口的设计者，开发人员会发现自己经常需要扮演记录其创造成果的角色。毕竟他们对于自己开发的API所涉及到的错综复杂的技术知识，最为了如指掌。然而，潜在的缺点也随之出现了，正是因为这种密切的联系，往往会导致技术文档过于专业，可能缺乏以更为友好的方法，让广泛的用户对其理解和使用。此外，将主要精力放在开发和维护API上，有时也会导致文档的优先级被放置到了次要位置。
因此，许多公司选择了另一种方法，来应对该挑战，即：让专业技术撰写人员参与到文档编制的过程中。这些人员拥有将技术理解与创新能力相结合的技能。他们的职责是在API的技术方面，为后续将使用该接口的开发人员，量身定制出清晰的内容“图谱”。
当然，这离不开上述两种角色的密切合作。也就是说，应用程序接口开发人员需要通过向技术撰写人员提供准确的、接口所需的信息记录，并按需澄清某些细节上的缺失，以确保合作所产生的文档具有全面性和连贯性。最终，这份精心制作的文档会在技术深度和易读性之间取得平衡，为目标受众提供清晰且有价值的资源。
API文档的基础部分通常称为概述。作为对API的简要介绍，它总结了应用程序接口的目的，概述了其独特的“卖点”。同时，它也可以强调该API在选用上的优势，以及能够为潜在用户提供哪些有价值的见解。例如，在天气类API的文档中，其概述需要简明扼要地指出：“本API可以提供全球各地的实时天气数据，可准确地预报或提供历史气候信息。”
作为文档的核心部分，教程在向用户介绍API的概念、以及实际用法方面，发挥着核心作用。其包含的循序渐进的指南，旨在帮助用户清楚地了解具体的集成过程，并展示适当的功能和使用场景。
身份验证详细说明了API提供方如何确保开发人员和最终用户的数据安全。鉴于可能存在多种身份验证方法，文档应阐明其中的每一种方法，以便用户全面了解如何安全地访问该API。例如，在社交媒体类API的文档中，身份验证细节可以向开发人员解释如何安全地获取访问其令牌。例如：“要访问用户数据，开发人员必须通过注册应用程序，并按照既定的身份验证流程获取OAuth 2.0访问令牌。”
API的端点定义，可以精确地定位应用程序接口与软件程序连接的位置。在描述这个被称为端点的交互点时，文档会包含服务器的URL或者是服务等详细信息，从而明确API与其他系统的接口方式。例如：对于消息类API而言，文档会将端点指定为“https://api.messaging.com”，以说明服务器的位置，进而方便开发人员与消息服务进行交互。
状态和错误代码对于开发人员了解API是否能够按照预期运行，是至关重要的。它包括了对于不同状态或错误情形的描述，以及开发人员该如何查找和解决遇到的问题的相关说明。例如，在文件存储类API的文档中，状态和错误代码可能包括：成功上传文件的“200 OK”、以及试图访问不存在文件的“404 Not Found”。通常，每段代码都会附有相应的说明和解决方法。
一旦用户掌握了API的内部工作原理，提供示例就显得水到渠成了。示例能够展示成功的API调用、响应、错误处理程序和其他常见操作。这种实用的示例可以增强用户对API的理解，并帮助用户有效地应用API。例如，针对以构造地图类API为基础的应用，示例可以将成功调用展示为“GET /maps/location?lat=37.7749&long=-122.4194”，并返回详细的位置数据。而错误示例则可以展示失败的验证尝试，并指导开发人员该如何正确地处理错误。
术语表可以通过提供技术术语、模式和其他专业术语的简明定义，来简化开发者对于文档的理解。这种方法既能够确保文档的清晰度，又不会给用户带来不必要的复杂技术问题。例如，在机器学习类API的文档中，“模型训练”等术语需要被链接到术语表的相应位置，进而提供简明的解释--“模型训练是使用标注数据指导算法，以提高其预测准确性的过程。”
了解受众是创建有效API文档的基础。我们应尽量避免假定受众具有统一的专业知识水平，而需要充分考虑到初学者和经验丰富的开发人员，在背景和技能水平上的差异，进而通过文档定制化，来满足他们的特定需求，真正为其所用。例如，对于初学开发者而言，请提供清晰的解释和代码示例，并尽量使用“读取数据”之类直白的语言，而不是“执行GET请求”这样的专业术语。
作为给开发人员的“见面礼”，下面我们来讨论如何将API文档的介绍部分写得内容丰满。
如前所述，介绍部分是开发人员与该API的第一次互动，因此要力求清晰易懂，给受众留下积极的初始体验。
下面，让我们来看某个API的介绍示例：
## 介绍范例
欢迎访问XYZ的API文档！无论您是经验丰富的开发人员，还是刚刚开始编码之旅的新手，本文档都可以成为您了解和使用XYZ API强大功能的入口。
**XYZ API的目的：**
XYZ API被设计为[此处可明确说明主要目的或功能]。它旨在[此处可说明能够解决的特定问题或提供哪些服务]。
**使用本文档的预期：**
在本文档中，您将能找到全面的指南、示例和参考资料，可帮助您将XYZ API集成到自己的项目中。无论您是在查找[此处可填特定用例]，还是在[此处可填常见问题]方面需要帮助，本文档都能为您提供线索。
**谁需要阅读本文档：**
本文档适合[此处可填目标受众]。无论您是前端开发员、数据科学家、还是API爱好者，您都能够在此找到有价值的信息，以增强XYZ API的使用体验。
开发人员通常会依靠各种示例，来了解如何有效地与API进行交互。因此，在展示代码片段时，我们应确保其简明扼要、注释清晰。这将有助于用户，尤其是那些对技术不太熟悉的用户，更容易地掌握API的功能。下面是一个Python示例：
# Python 示例Pythonimport requestsurl = "https://api.weathernow.com/current"response = requests.get(URL)data = response.json()print("Current temperature:", data['temperature'])命名规则的一致性可以提高文档的可读性。通过对端点、参数和响应采用清晰统一的术语，可以避免不必要的混淆，毕竟不一致性往往会导致误解和错误的产生。此外，保持标准化的命名方法，可以为开发人员创造更顺畅的学习体验，使他们能够更容易地将您的API集成到自己的项目中。例如：请不要交替使用“temp”、“temperature”、以及“temp_data”，而需要在整个文档中统一为“temperature”的术语。
开发人员需要根据有关预期输入参数和API响应结构的相关记录，来了解应如何格式化请求，并解析API返回的数据。因此，我们需要为请求和响应提供现实的示例，以弥合理论解释和实际执行之间的差距，让开发人员无障碍地使用您的API。下面是一个典型的请求示例代码：
// 请求示例JSON{ "city": "New York", "units": "metric"}// Response Example{ "Temperature": 23, "condition": "Clear", "humidity": 50}由于清晰的错误处理信息更利于排障，因此我们需要在文档中体现潜在的错误代码、信息及其含义，以确保能够指导开发人员该如何处理这些错误。这种积极主动的方式，不仅能够帮助开发人员迅速解决问题，还可以减少他们的挫败感与困惑，进而带来积极的用户体验。例如：一旦发现被提交的请求中没有需要必填的参数，API则应给出诸如“缺少必填参数：城市”等明确的错误信息。
文档中应体现与API相关的任何速率限制信息，以协助开发人员有效管理API的使用情况，进而避免因速率限制问题而造成的服务中断。此外，文档还应包含检查API的当前使用情况和处理限速的错误详细信息，以帮助开发人员优化应用本身的性能，并确保其能够与该API进行更顺畅的集成。例如：“我们的API速率限制为：每小时100个请求。如果超过此限制，您将收到‘429过多请求’的状态代码。若要检查您的使用情况，请在响应中包含‘X-Rate-Limit-Remaining’标头”。
定期更新文档可以方便开发人员了解API的相关变更、新增功能、以及废弃了的功能。因此，通过文档来传递版本信息、维护更新日志、以及突出修改的内容，都将有助于在用户群中培养一种针对API可靠性的信任感，特别是在您能够主动更新文档的情况下。例如，在发布说明中，您可以提及：“2.0版引入了新的端点‘/forecast’，可用于扩展天气预测”。
文档中应鼓励开发人员分享经验、提出问题与建议。这种双向交流将有助于您及时解决潜在的问题，更好地了解用户需求，从而不断改进API的功能及其文档。例如：“我们非常重视您的反馈意见！如果您有任何疑问、建议或遇到任何问题，请联系我们的支持团队：support@xyz.com”。
清楚地阐明您的指令，避免对用户已有的知识做出假设。请记住，模棱两可或含糊不清的文档只会导致误解和实施错误。只有清晰的解释，才能确保那些经验有限的开发人员，也能自信地遵循您的文档。例如，请不要简单地使用一句“只需请求我们的API即可”，而需详细地说明：“请向‘https://api.weathernow.com/current’发送HTTP GET请求，以检索当前的天气信息。”
专业术语虽然表达准确，但是也会妨碍用户的理解。为了在准确性和易读性之间取得平衡，最好的一种办法是：在必要时，对技术术语进行定义和解释，让开发人员在理解文档时不会产生歧义或是感到突兀。例如：将“利用异步通信范式提高可扩展性”的措辞改为“允许同时处理多个请求，进而提高性能”。
密集冗长的段落会让人缺乏继续阅读的耐性，进而导致重要细节被忽略。对此，请确保使用要点、列表、短句、以及标题等分段格式，来有效地组织内容，从而在提高文档可读性的基础上，方便用户在文档中快速找到所需的信息。例如：
综上所述，有效编写API文档是一个多层次的过程。它既需要深入了解受众，又需要提供清晰的介绍，实用的代码示例、鼓励用户反馈，并致力于不断的改进。相信通过遵循上述介绍的步骤和实践，您也可以创建出让开发人员倍感实用，并使其能够与API无缝集成的优秀说明文档。
陈峻（Julian Chen），51CTO社区编辑，具有十多年的IT项目实施经验，善于对内外部资源与风险实施管控，专注传播网络与信息安全知识与经验。
原文标题：How to Write API Documentation: Best Practices and Examples，作者：Toluwani Folayan
本文链接：http://www.28at.com/showinfo-26-60929-0.html编写API文档的优秀实践与示例
声明：本网页内容旨在传播知识，若有侵权等问题请及时与本网联系，我们将在第一时间删除处理。邮件：2376512515@qq.com
Copyright © 2016-2023 天津谷骐科技有限公司 版权所有 sitemap.xml
违法及侵权请联系：2376512515@qq.com 津ICP备18001702号
津公网安备 12010102000574号
