在这门有关编写REST API文档的课程中，我不只是在谈论抽象概念，而是通过直接的动手方法将REST API关联起来。首先，您将通过使用简单的天气API在站点上放置天气预报来了解API文档。

使用API​​时，您将了解端点，参数，数据类型，身份验证，curl，JSON，命令行，Chrome的开发者控制台，JavaScript等。其思想是，您不必通过独立于上下文来学习这些概念，而可以通过使用API​​来沉浸在真实的场景中来学习它们。浸入实际场景中会使这些工具和技术变得更有意义。

然后，我们将过渡到REST API的标准，工具和规范。您将了解API文档中的必需部分，分析来自多家公司的REST API文档的示例，了解如何加入开源项目以获取经验，等等。

目录

• 关于REST API
• 从实践到文档
• 该课程适合谁
• 课程组织
• 顺序和活动
• 这门课程是否可以帮助您找到API文档中的工作？
• 无需编程技能
• 您需要什么
• 测试你的设置

关于REST API

简而言之，REST API(Web API的一种)涉及请求和响应，与访问网页不太相似。您对存储在服务器上的资源进行请求，服务器将以请求的信息进行响应。用于传输数据的协议是HTTP。“ REST”代表代表性状态转移。

REST API涉及通过HTTP协议的请求和响应

从实践到文档

在本课程中，您像开发人员一样练习使用API​​之后，您将转变观点并“成为技术作家”，负责记录工程师添加到API的新端点。作为技术作家，您将解决REST API文档中参考主题的每个元素：

1. 资源说明
2. 终点和方法
3. 参量
4. 请求示例
5. 回应范例

通过研究这些部分，您将对如何记录REST API有深入的了解。您还将学习如何记录API的概念性部分，例如入门指南，状态和错误代码，请求授权等。

最后，您将深入研究发布REST API文档的各种方式，探索GitHub，Jekyll等工具和规范以及其他按文档编码的方法。您将学习如何利用模板，构建交互式API控制台，以便用户可以尝试请求和查看响应，以及如何通过版本控制来管理您的内容。

我们还将深入研究诸如OpenAPI规范和Swagger UI(为OpenAPI规范提供工具)之类的规范。此外，您还将学习如何记录本机库API并生成Javadoc。在整个课程中，我将通过动手练习和演示将这些概念置于真实，适用的环境中。

该课程适合谁

本课程主要服务于以下受众：

• 寻求从GUI文档过渡到面向开发人员的更多API集中文档的专业技术作家。
• 学生将学习如何为在技术通讯领域取得成功而进行技术上的准备，而该领域正越来越侧重于开发人员文档。
• 正在编写自己的API并希望了解技术文档的结构，术语和样式的最佳做法的开发人员。

课程组织

‌下面提供了本课程各部分的说明：

• I：REST API简介：REST API在市场上正在蓬勃发展，并且网络正在成为互连API的混搭。REST API包括对Web服务器的请求和响应。对于可以编写开发人员文档的技术作家来说，工作前景很热。本课程将帮助您深入了解API文档，尤其是在完成许多项目组合构建活动时。
• II：像开发人员一样使用API​​：扮演开发人员的角色将有助于您更好地了解开发人员的需求，以及开发人员通常在API文档中寻找的内容。开发人员经常使用诸如Postman或curl的工具进行呼叫。他们查看响应的结构，并将所需的信息动态集成到网页和其他应用程序中。
• III：记录API端点：API端点的参考文档包括五个常规部分：资源描述，端点和方法，参数，示例请求以及示例响应和模式。要记录API的参考端点，请为每个部分提供详细信息。
• IV：OpenAPI规范和Swagger：OpenAPI规范提供了描述REST API的正式方法，并包括上一节“记录API端点”中提到的所有参考部分。诸如Swagger UI之类的显示框架可以解析OpenAPI规范并生成交互式文档，使用户可以在了解API的同时试用端点。
• V：测试API文档：测试文档对于提供准确，全面的信息至关重要。使用API​​和开发人员文档，由于高度的复杂性和工程要求，技术编写者可能倾向于仅获取工程师提供给他们的信息并将其批发地合并，而无需亲自对其进行测试。但是，仅发挥编辑/发布功能，可以将您的角色减少为工程师的秘书。
• VI：API文档中的概念性主题：虽然API中的参考主题通常最受关注，但概念性主题(例如入门教程，有关授权的信息，速率限制，状态和错误代码，快速参考指南以及其他主题)构成了以下主题：文档的一半。这些主题通常由技术作家而不是工程师处理。您可以通过查看API文档是否包括这些概念性主题来部分评估API文档的质量。
• VII：代码教程：本节介绍创建代码教程的策略。我仍在开发本节，因此很多内容正在建设中。
• VIII：发布API文档：API文档通常遵循以文档为文档的工作流程，其中编写和发布文档的工具与开发人员用来编写，管理，构建和部署代码的工具紧密匹配。Docs-as-code涉及使用Markdown等轻量级格式，通过Git或其他版本控制进行协作，使用静态站点生成器构建文档站点，并通过连续构建模型进行部署，在此过程中，当您按入时在服务器上进行构建提交到特定分支。
• IX：在API文档空间中蒸蒸日上：要获得API文档工作并蒸蒸日上，您需要通过撰写作品集来证明自己的技术才能。产品组合应包括为开发人员编写的文档样本。建立此项目组合的一种方法是通过开发一个开源项目。您还需要居住在可提供API文档工作的技术中心，例如加利福尼亚，德克萨斯州，纽约或弗吉尼亚州。总体而言，要在开发人员文档空间中蓬勃发展，您需要不断学习健康的代码，这可能是一个挑战。
• X：本机库API：本机库API指Java，C ++或其他特定于编程的API。在此模型中，您无需下载代码库并将其集成到您的项目中，而无需通过网络请求信息。该库直接编译到您的应用程序的内部版本中(而不是像REST API一样通过Web协议进行访问)。尽管这种类型的API不太常见，但我还是在此处将其部分包括在内，以阐明是什么使REST API与本机库API如此不同。
• XI：API词汇表和资源：API文档范围充满术语，首字母缩写词和许多新术语。本词汇表提供了术语和定义的列表。此外，本节还包含其他练习和信息，例如，更多用于调用API的活动或有关替代规范的更多信息。

顺序和活动

顺序和活动您无需按顺序阅读各个部分，您可以根据需要随意跳过。但是，前面的某些部分(例如，有关使用REST API(如开发人员和Documenting端点)的部分)在相同的Weather API场景下遵循某种顺序。

由于本课程的目的是帮助您学习，因此许多活动需要动手编码和其他练习。除了学习活动外，还进行了概念上的深入研究，但重点始终是边做边学。在有动手活动的地方，我通常在标题部分中添加此图标：。

其他主题的标题中带有“活动”一词。这些活动被集成到各个部分中，但是您还可以在Workshop活动中看到活动的合并子集。这些是我们在现场研讨会中进行的活动。

我将这里的内容称为“课程”，而不是书或网站，主要是因为在每个部分中我都进行了很多练习，而且我发现想要学习API文档的人们更喜欢动手实践“当然”的经验。

这门课程是否可以帮助您找到API文档中的工作？

人们参加本课程的最常见原因是过渡到API文档。本课程将帮助您进行过渡，但您不能只是被动地阅读内容。您需要执行每个部分中概述的活动，尤其是涉及使用开源项目中的内容的主题。这些活动对于建立投资组合的经验和信誉至关重要。我在“获取API文档”和“蓬勃发展”中提供了更多详细信息。

无需编程技能

至于本课程所需的技术背景，您不需要任何编程背景或其他先决条件，但有助于了解一些基本的HTML，CSS和JavaScript。如果您确实熟悉编程概念，则可以快速浏览某些部分，然后跳到您想了解更多的主题。不过，本课程假定您是新手。

本课程中的某些代码示例使用JavaScript。JavaScript可能是也可能不是您在记录REST API时实际使用的语言，但是很可能会有一些编程语言或平台变得很重要。

JavaScript是最熟悉的最有用和最简单的语言之一，因此，在此REST API文档介绍的代码示例中，JavaScript效果很好。JavaScript允许您仅通过在浏览器中打开代码(而不是在IDE中进行编译)来测试代码。(如果需要的话，我在这里提供了JavaScript速成课程。)

您需要什么？

您需要使用以下一些工具来完成本课程中的活动：

• 有电源线的笔记本电脑。在进行各种活动时，请确保带好计算机和充电线。
• 文本编辑器。如果您还没有收藏的文本编辑器，请下载Sublime Text，它在Mac和Windows上都可以正常运行，并且是免费的。如果您有其他喜欢的文本编辑器(例如，Visual Studio Code，Atom或什至Notepad ++)，也可以使用。只要确保您可以用纯文本编写代码即可。
• Chrome浏览器。Chrome提供了一个Javascript控制台，可以很好地检查JSON，因此我们将使用Chrome。另外，为了在浏览器中更轻松地读取JSON响应，请安装JSON Formatter Chrome扩展程序。
• Postman。Postman是一款应用程序，可让您通过GUI客户端发出请求并查看响应。确保您下载的是应用程序，而不是Chrome扩展程序。
• curl。curl对于从命令行向端点发出请求至关重要。Mac已经内置了curl，但默认情况下Windows上可能不提供它。(某些Windows 10内部版本已在Powershell中使用它。)在Windows上，打开命令提示符并键入curl -V。如果尚未安装，请访问confusedbycode.com/curl并安装一个版本(通常是“具有管理员权限(免费)，64位”)。关闭并重新打开命令提示符，然后尝试再次键入curl -V。
• Git。Git是开发人员经常用于在代码上进行协作的版本控制工具。对于Windows，请参阅https://gitforwindows.org/来设置Git和Git BASH终端仿真器。对于Mac，请参阅下载Git。
• GitHub帐户。GitHub将用于各种活动，有时会演示Git工作流，而有时会用作开发人员工具的身份验证服务。如果您还没有GitHub帐户，请注册一个。
• Stoplight Studio编辑器。在使用OpenAPI规范时，我们将使用Stoplight Studio编辑器。Stoplight Studio提供了可视化建模工具，可用于OpenAPI规范。Stoplight提供了该浏览器的Web浏览器版本和独立的应用程序版本。我们将使用网络浏览器版本，因为它提供了更完整的功能(例如尝试请求)。转到https://stoplight.io/p/studio并使用Gi​​tHub登录。
• OpenWeatherMap API密钥。我们将使用OpenWeatherMap API进行一些练习。OpenWeatherMap API密钥需要花费几个小时才能生效，因此最好提前获取API密钥-然后，当您进入OpenWeatherMap API活动时，一切都会准备就绪。要获取(免费的)OpenWeatherMap API密钥，请访问https://openweathermap.org/。点击顶部导航栏中的注册并创建一个帐户。注册后，OpenWeatherMap将API密钥发送给您的电子邮件。您也可以在登录并在信息中心中单击“ API密钥”选项卡时找到它。将密钥复制到可以轻松找到的位置。

测试您的设置

过去，人们要求进行一些测试以检查笔记本电脑的设置是否正确。

• 如果要测试Postman是否工作，请打开Postman应用程序并将其粘贴到GET框中：https://api.openweathermap.org/data/2.5/weather?zip=95050&units=imperial&appid=126cac1a482f51de0f1287b45ae2bf9a。
• 然后单击发送。如果您收到回复，则说明该回复正常。(在极少数情况下，有时人们会对计算机进行安全限制，以阻止所有网络访问。)如果要测试是否安装了curl，请打开Terminal(在Mac上)或Command Prompt(在Windows上)，然后粘贴curl -X GET“ https://api.openweathermap.org/data/2.5/weather?zip=95050&units= imperial＆appid = 126cac1a482f51de0f1287b45ae2bf9a”。如果收到JSON响应，那就很好。
• 要检查是否已安装Git，请打开Terminal(在Mac上)或Command Prompt(在Windows上)，然后键入git --version。如果已安装，则会看到该版本。

本文章翻译来源自海外课程