文章采集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 允许您通过 Bilibili Travel 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 何时成功调用、何时不成功，并能够解决他们遇到的任何错误。通常，此信息放置在其自己的页面上。这是 express 100API 文档中的一个示例。

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

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

　　最好的 API 文档是为完全不熟悉 API 的初学者和非常熟悉它的开发人员编写的。本文档需要尽可能避免过多的技术术语，并尽可能提供额外的上下文信息或文档的内部链接。它还需要提供诸如“入门”之类的内容以及新手用户需要的示例和教程，但更高级的用户可以跳过。

　　为了确保用户可以选择他们想要的东西，API 文档必须以导航的方式设计。最佳实践是使用页眉和侧边栏，以便用户无需上下滚动页面即可导航到文档的另一部分并提供搜索功能。其他设计考虑因素包括排版、配色方案和布局。三列布局被认为是收录大量代码示例的文档的理想选择。无衬线字体和对比色链接也是不错的设计选择。

　　7.使 API 文档保持最新

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

　　如何阅读 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，并且同事确保他们可以与其他非技术同事一起使用它。