文章采集api(七个步骤逐步介绍如何阅读API文档和测试？(组图))

　　文章采集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主访问上千家推荐的酒店。网站 上甚至还有一个用于集成 Yoda 翻译器的 API。虽然每个 API 的作用不同，但是每个 API 文档都应该涵盖一些基础知识。让我们看看下面的一些例子。

　　验证

　　由于认证对于保护API数据以及开发者和最终用户的数据安全非常重要，API通常有多种认证方案，因此API文档中必须对每一种认证方式进行说明，以便用户能够正确获取Authorize并使用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 何时成功调用、API 何时未成功调用，并能够解决他们遇到的任何错误。通常，此信息放置在其自己的页面上。这是 Express 100 API 文档中的一个示例。

　　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​​。当然，你不需要了解概览的每一个细节，但你应该粗略地浏览一遍。

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

　　对函数的深入理解

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

　　例如，假设您想通过快递100的API实现如下物流查询功能：-在电商网页/APP/小程序中，客户在订单详情中查看所购商品的物流地图轨迹，并显示物流跟踪文字信息一起。顾客

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

　　通读 API 文档教程

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

　　记录 API 信息更改

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