什么是API？ [如何编写和阅读API文档]

随着API在互联网时代中变得越来越普遍，不仅是编程人员会用到，现在也会要求产品经理或互联网运营会调试和对接API。看这篇文章的你可能会使用或开发API，或者两者兼而有之。 因此，对你来说，不仅要了解如何编写，还要了解如何阅读API文档和测试。

什么是API文档？你也可以将API文档视为双方之间的服务协议。文档概述了当第一方发送某种类型的请求时，第二方及其软件将如何响应。这些类型的请求（称为API调用）在文档中进行了描述，以便开发人员知道他们可以用API做什么以及如何进行操作。

优质的API文档描述了它们的端点，解释了为什么要使用它们，并提供了非常具体的示例来说明如何使用它们-所有这些方式对于初学者和高级用户都是一样清晰明了的。指示不明的API文档过于技术性和基于文本描述，因此并非所有用户都可以正确使用它。

下面，我们将通过七个步骤逐步介绍如何编写优质的API文档。

了解用你API的用户

描绘你的用户旅程

从基础功能陈述开始

添加代码示例

列出您的状态代码和报错消息

用大白话来编写和设计API文档

让API文档始终保持最新的状态

1.了解用你API的用户

与任何内容影响策略计划或UI设计过程一样，编写API文档的第一步是了解目标受众。这需要了解您定位的用户类型，内容需要为他们提供的实用价值以及符合他们实际场景的方式。

在编写API文档时要记住两个主要的用户组。一组用户是API文档的直接使用者，因此他们只需要查看教程和代码示例。该小组主要是开发人员。另外一组用户会评估API功能、价格、费率限制、安全性等等因素，以此了解该API如何与他们的业务需求和目标保持一致。该小组主要由CTO和产品经理以及一些开发人员组成。

你必须牢记这两个角色，以确保文档为每个读者提供良好的体验。

2.描绘你的用户旅程

与任何产品一样，API必须在买方旅程的每个阶段都提供内容。这意味着文档应说明API可以做什么（或可以解决什么问题），其提供的功能和端点的多样性以及与竞争对手的不同之处。

API文档应回答的一些基本问题是：

1.为什么要使用这个API？

2.如何获得对不同工具和端点的访问权限？

3.获得权限后的下一步操作是什么？

4.如何使用某些特定功能？

3.从基础功能陈述开始

每个API和功能都是独特或唯一的。比如说，有的API可将微博照片嵌入到电商平台详情页中。有的API可让你通过B站旅行UP主访问数千家推荐酒店。甚至还有的API，用于在网站上集成Yoda翻译器。虽然每个API的作用不一样，但是每个API文档都应涵盖一些基本知识。让我们在下面看一些例子。

身份验证

由于身份验证对于保护API数据和开发人员及终端用户的数据安全来说是非常重要的，因此API通常会有多种身份验证方案，所以API文档必须说明其每种身份验证方法，以便用户可以获得授权和正确地使用API。例如，YouTube数据API支持两种类型的授权凭证。其文档说明了如何使用OAuth 2.0以及如何获取API密钥，以便用户可以选择自己更熟悉的验证方法。

速率限制

像用户身份验证一样，速率限制可以帮助防止传输意外或API滥用。 API速率限制是您可以在给定时间内向API发送请求的次数。这些限制必须在API文档中明确说明，以便用户知道如何正确使用API及其功能。此信息最常在“使用条款”中找到。

使用条款

使用条款（或服务）是服务提供商与想要该服务的使用人之间的法律协议。后者必须同意遵守这些条款才能使用该服务。在API文档中，使用条款必须明确定义API使用者在理想情况下应如何使用API。这将有助于确保服务使用者充分利用API平台和功能。

内容变更日志

必须让API使用者了解他们使用的API的任何贬低，这一点很重要。变更文档可以帮助他们正确地维护其应用程序，并充分利用API平台的功能。案例：Twitter的API文档具有一个更改日志，其中记录了对Twitter开发人员平台所做的所有更改，包括新功能和新产品。

4.添加代码示例

API文档有两个主要目标：使开发人员尽可能容易地使用API，并使他们快速了解API的全部功能。实现这两个目标的好方法是为每个API端点提供代码示例。这样，开发人员可以了解端点的最关键功能，并从一些案例代码开始着手，然后直接在案例代码上调整参数以满足他们的实际需求和对接规范。

5.列出您的状态代码和错误消息

API文档应明确概述用户在进行API调用时可能期望的状态代码和错误消息。理想情况下，每个响应都应附有简短说明，以便用户了解何时成功调用了API，何时未成功调用，以及能够解决自己遇到的任何错误。通常，此信息放置在其自己的页面上。这是快递100API文档中的示例。

6.用大白话来编写和设计API文档

如果你想要以一种易于用户阅读和浏览的方式编写，构建和设计API文档。这意味着根据用户的使用场景和他们的需求来呈现和组织文档的内容信息。用户的使用场景是与用户在哪里，何时，为什么以及如何寻找内容并与内容进行互动有关的所有内容。他们的需求还包括他们的目标，行为和期望。

最好的API文档是同时为根本不熟悉该API的初学者和非常熟悉该API的开发人员而编写的。这份文档需要尽可能地避免过多技术术语，并尽可能提供了附加的文档的上下文信息或内部链接。它还需要提供，如“入门”以及示例和教程，这些都是新手用户需要的内容，而更高级的用户则可以跳过。

为了确保用户可以选择所需的内容，在设计API文档时必须进行导航方式。最佳做法是使用标头和侧边栏，以便用户无需在页面上上下滚动即可导航到文档的另一部分并提供搜索功能。其他设计注意事项包括版式，配色方案和布局。三列布局被认为是带有大量代码示例的文档的理想选择。无衬线字体和对比鲜明的彩色链接也是不错的设计选择。

7.让API文档始终保持最新的状态

为了确保API使用者可以获得最佳体验和持续不断地吸引新用户，API提供者必须时常维护自己的API文档。在过去，API文档以PDF或静态网页的形式存在，这会让文档难以更新。现在，有一些工具可以帮助您创建可以自动更新的动态和交互式文档。 Redocly和SwaggerUI是两个比较常见的实际示例。

如何阅读API文档

如果你只是API使用者，而不是API服务提供者，那你就需要了解如何阅读一份API文档。尽管编写和阅读它的方法相似（寻找基本原理，尝试代码示例等），但它们并不是完全相同。让我们仔细看看如何阅读一份API文档，以了解使用特定API可能实现的功能。

从文档概述开始

大多数API文档将首先概述API的功能、如何连接API以及如何正确使用API。当然，你不需要了解概述的每个细节部分，但是你应该大致浏览它一遍。

以快递100的API文档为例子，首先快递100的API文档说明了快递100的API用途，使用的协议和语言以及其身份验证方案。在左侧边栏的“快速链接”部分，您将找到指向其使用指南和速率限制，测试帐户，变更日志以及开始使用API所需的所有其他内容的重要链接。

深入了解一种功能

了解API概述后，请浏览API参考文档，其中列出了API的所有功能（也称为方法）。在这一点上，没有必要彻底阅读或记住所有内容。相反，请仔细研究你特别感兴趣的功能通过查看其参数和示例，你可以了解是否可以成功使用API来执行想要执行的确切操作。

例如，假设你想要通过快递100的API实现以下的物流查询功能： - 在电商网页/APP/小程序中，顾客在订单详情里查看购买商品的物流地图轨迹和物流轨迹文字信息一同展示给顾客

• 可视化订单的在途状态以及获得物流途径城市的信息，监控快递时效

• 预估包裹的到达时间，以及提示包裹还需多长时间到达，识别快递状态

• 发送提醒客户签收短信

在这种需求驱动下，你可以导航到“接口文档” 然后，查看其代码语言、参数、响应和错误消息等等。

通读API文档教程

现在你已经知道是否可以使用API来实现你要的需求了，请查看教程。由于最好的API文档应该可以帮助用户快速入门，因此大多数文档都将包含用于完成任务的详细教程。你应该通读至少一篇教程，以了解哪些细节层次和示例是需要仔细学习的。如果你想要了解电商快递物流API的好处，这里有篇文章《什么是电商API？这是它能给商家带来12种运营好处》，详细介绍了他们的优缺点，有兴趣你可以阅读一下，说不定你会发现意外的惊喜。

记录API信息变更

随着越来越多的公司提供API服务来形成高集成的用户体验，知道如何编写和阅读API文档正变得越来越有价值。在创建或评估API文档时，请确保你的API稳定易于阅读和浏览，并清楚地将API的价值传达给开发人员和非开发人员。 这样可以确保技术出身的用户可以开始快速和正确你的API，同事也要确保他们可以与其他人非技术出身的同事一起使用。