在“ API概述”部分之后，通常会有一个“入门”部分，其中详细介绍了用户开始使用API??所需的第一步。本节通常包括从头到尾的整个过程，并尽可能简单地对其进行压缩。

目录

• API概述的目的
• Postman运行按钮
• 入门主题示例
• PaypalTwitterParse ServerAdsenseAerisWatson and IBM Cloud
• 入门教程活动

API入门概述的目的

入门主题有点像开发人员文档中的典型Hello World教程，但是带有API。此教程将会指导用户输出最简单的输出响应。对于Hello World教程，最简单的输出可能只是显示“ Hello World”的消息。对于API，可能是最基本请求的成功响应。

《 Hello World》教程和《入门指南》都具有相同的目标：向用户展示如何使用框架，API或其他系统来获得最简单，最简单的结果，从而使他们对它的使用方式有一种端到端的感觉。

举个例子，您可以为您的API提供一个通用的基本用例，并说明如何构造请求以及返回的响应。如果开发人员可以成功进行该调用，那么他或她也可能也可以成功进行其他调用。

入门教程可能涉及以下内容：

• 申请帐号
• 获取API密钥
• 提出要求
• 评估回应

在文档主页上放置指向入门教程的链接。使开发人员尽可能容易地使用API??来获得一些结果。如果这意味着使用预先设置的帐户或设置配置，请考虑这样做。

Postman运行按钮

在入门教程中，考虑包括“在Postman中运行”按钮。（Postman是REST API GUI客户端，我们在前面的“通过Postman提交请求”中进行了探讨。）如果您的API端点与Postman集成在一起，则可以将Postman集合导出为小部件以嵌入HTML页面。

“在Postman中运行”按钮提供了一个按钮，单击该按钮后，会将您的API信息导入到邮递员中，以便用户可以使用邮递员客户端运行呼叫。这样，“运行邮递员”按钮提供了一种将端点的交互式，试用版API资源管理器导入到网页中的方法。

要尝试在Postman中运行，您可以将OpenAPI规范导入Postman或手动输入API信息。然后，查看有关如何创建“在Postman中运行”按钮的Postman文档。

您可以在此处看到“在Postman中运行”的许多演示。这些演示中的许多演示都在Postman的API网络中列出。

这是使用OpenWeatherMap API的天气端点（在先前的教程中我们曾使用过）的“在Postman中运行”的演示：

单击按钮时，系统将提示您在Postman客户端中打开集合：

Postman提供了许多开发人员都熟悉的功能强大的REST API客户端。它允许用户自定义API密钥和参数并保存这些值。尽管Postman并未像Swagger UI一样提供浏览器内体验来尝试调用，但是Postman客户端在许多方面都更加有用，因为它可以让用户配置和保存他们进行的呼叫。内部开发人员在测试和探索功能时经常使用Postman来保存和存储API调用。

尤其是如果您的用户已经熟悉Postman，“在Postman中运行”是一个不错的选择（特别是作为许多用户试用API的一种选择），因为它使用户可以轻松生成所需的代码来进行几乎任何请求语言。它为用户提供了一个起点，让他们可以在您的信息基础上创建更详细和自定义的调用。

如果您的文档中还没有“试用”功能，则“运行Postman”按钮可以轻松地为您提供这种交互性，而无需您牺牲文档的真实性。

缺点是您的参数和端点描述不会被Postman拖入。另外，如果用户不熟悉Postman，他们可能会有点难以理解如何使用它。相比之下，直接在浏览器中运行的“试用”编辑器往往更加简单明了，并且在集成文档方面做得更好。

入门主题示例

以下是API中的一些示例入门主题。如果您比较入门的各个部分，您会发现其中一些详细而又高级又简短。通常，您可以抓住开发人员的思想越多越好。但是，本教程应该仍然简短，而不仅仅是与其他文档重复。关键是要向用户显示使用API??的从头到尾的完整过程。

Paypal

Paypal入门教程包含很多详细信息，从授权，请求和其他详细信息开始，然后进行首次调用。尽管不是那么简短，但是这种详细程度有助于使用户了解他们所需的信息。该格式干净且易于遵循。

?

Twitter

?Twitter的入门页面包含几个针对不同开发目标的入门部分。文本简洁明了，易于理解。本教程经常链接到其他文档，以获取更多详细信息。为了简洁起见，您可能需要遵循相同的策略-简短并链接到其他更详细的页面。

?

Parse Server

Parse Server教程通过各个步骤提供了大量详细信息和内容。有关连接应用程序和在其他地方运行服务器的更详细的步骤，本教程链接到更多信息。

Adsense教程为平台入门提供了一些基本的先决条件。设置完成后，它将提供一个“快速入门教程”。该教程从头到尾引导用户完成一个简单的场景，帮助他们了解产品及其功能。

?

Aeris

Aeris天气入门提供了用于设置应用程序然后以几种流行语言之一进行请求的信息。虽然以特定语言显示代码无疑对使用这些语言进行编程的程序员更有帮助，但是代码示例可能与其他用户无关（例如，Java开发人员可能会发现Python代码无关，反之亦然）。专注于特定语言通常是一种折衷。

?

Watson and IBM Cloud

Watson和IBM Cloud入门教程列出了三个步骤。不过，这不是一个端到端的入门教程。它只是让用户开始为您的项目选择服务。最后，您开始使用Watson Dashboard进行编码。理想情况下，入门教程应该可以帮助用户看到一些切实的输出，但是是否可行取决于您的API。

?

入门教程活动

使用您确定的开源项目，确定入门教程。然后回答以下问题：

• API是否有入门教程？
• 入门教程会引导您完成端到端方案吗？
• 您可以成功完成入门教程中的所有步骤吗？
• 入门教程需要多长时间才能完成？
• 为了简化说明并使其简短，文档是否对您的技术水平和对领域的熟悉程度做出了假设？

?