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

随着API在互联网时代中变得愈来愈广泛，不只是编程人员会用到，如今也会要求产品经理或互联网运营会调试和对接API。看这篇文章的你可能会使用或开发API，或者二者兼而有之。 所以，对你来讲，不只要了解如何编写，还要了解如何阅读API文档和测试。

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

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

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

1. 了解用你API的用户
2. 描绘你的用户旅程
3. 从基础功能陈述开始
4. 添加代码示例
5. 列出您的状态代码和报错消息
6. 用大白话来编写和设计API文档
7. 让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服务来造成高集成的用户体验，知道如何编写和阅读API文档正变得愈来愈有价值。在建立或评估API文档时，请确保你的API稳定易于阅读和浏览，并清楚地将API的价值传达给开发人员和非开发人员。 这样能够确保技术出身的用户能够开始快速和正确你的API，同事也要确保他们能够与其余人非技术出身的同事一块儿使用。