简介

OpenAPI 规范 (OAS) 允许描述通过 HTTP 或类似 HTTP 的协议访问的远程 API。此描述可以存储在一个或多个文档中（例如本地文件或 HTTP 可访问的网络资源），称为 OpenAPI 描述 (OAD)。本章解释了为什么用 OAD 描述您的 API 是件好事，以及为什么它可能对您有吸引力。

首先介绍了“API”的概念，并介绍了使用机器可读格式描述 API 的优点，然后介绍了使用 OAS 格式的好处。在最后一节，API 描述的演变将与简要的历史总结放在一起。

如果您已经熟悉机器可读 API 描述和 OpenAPI 的好处，特别是 OpenAPI，您可以跳到下一章，OpenAPI 规范解释。

什么是 API？

应用程序编程接口 (API) 定义了 两块软件 之间允许的交互，就像用户界面定义了用户可以与程序交互的方式。

API 由可以调用的方法列表（要发出的请求）、它们的参数、返回值以及它们所需的任何数据格式（以及其他内容）组成。这相当于用户与移动应用程序交互的方式仅限于应用程序用户界面中的按钮、滑块和文本框。

API 可以是 本地 的，其中两个交互方都在同一台机器上运行。例如，操作系统提供给其应用程序的 Windows API，任何 C 编译器提供给正在编译的程序的标准 C 库，或者 TensorFlow 库提供给使用它的程序的 TensorFlow API。

但是，本文档侧重于 远程 API，其中交互方在不同的机器上运行并通过网络进行通信。例如，公开的天气服务提供机器可读的天气预报，供网页或移动应用程序使用，或者 Twitter 允许第三方应用程序通过其网络发送消息。

为了总结定义，通过 API 提供服务的方称为 提供方，而请求这些服务的方称为 消费者。

在计算机科学中，使用 API 是一种日常实践，因为它们的好处是毋庸置疑的。仅举最突出的例子

  • API 提供 信息隐藏：API 的两端（提供方和消费者）都不知道另一方的实现细节。只要双方都遵守 API，就可以根据需要进行更改，而另一方甚至不会注意到。

  • API 也称为 契约，因为它们被认为是不可破坏的：提供方 承诺 不更改其 API，并承诺在未来几年内继续遵守它。有了这个承诺，消费者就可以开始开发他们自己的部分，并放心地依赖 API 提供的功能。

现在，为了让所有相关方都遵守同一个 API，必须对它进行精确定义。下一节将介绍传统上是如何实现这一点的。

通过文档描述 API

API 通常附带 参考指南；一份向开发者解释如何使用 API 的文献。

不幸的是，每个从事软件开发的人员都熟悉以下一个或多个问题

  • 文档不清，导致因解释差异而产生错误。
  • 文档不完整或不存在。
  • 信息过时。
  • 信息使用读者不理解的语言。

在这些情况下，为了找到他们需要的信息，开发人员可能不得不阅读源代码（如果有的话）、调试程序或分析网络流量，这些都是巨大的 时间浪费。

此外，仅通过文档描述的 API 使用中的错误只有在运行时才能发现，这也是另一种时间浪费。

下一节将展示如何通过以自动化工具可以使用的格式指定 API 来缓解其中的一些问题。

使用 OAS 描述 API

API 描述文件（有时称为 契约）是 API 的 机器可读 规范。它应该尽量 完整 且 完全详细，尽管绝对完整通常不是必需的。此外，就像法律契约一样，它越 明确，就越有用。

它相对于仅供人类阅读的文档的主要优势在于它允许进行 自动化处理，从而打开了 本指南开头列出的优点 的大门。

首先，可以从 API 描述文件轻松地生成供人类阅读的文档，包括可用方法列表及其详细信息。这作为构建过程中的一个步骤完成，可以轻松地防止文档不同步。

此外，工具可以使用 API 描述来 生成样板代码（以任何编程语言），以构建提供方和消费者应用程序。只需要添加业务逻辑，生成的代码就会处理所有 API 处理，从而消除另一个错误来源，并确保代码和文档匹配。此外，如果传递给 API 的数据必须满足任何约束，则样板代码可以自动验证这些数据，从而消除更多手动代码。

仅举另一个可能性，API 描述文件可能包括示例，这些示例可以用作 自动生成模拟服务器 的响应。这使得即使在 API 提供方代码编写之前也能进行早期 API 测试。

出于以上所有原因以及更多其他原因，在设计新 API 时强烈建议使用机器可读的描述。

多年来，出现了多种 API 描述格式（称为 规范）。下一节列出了在创建新 API 时使用最广泛的规范 OpenAPI 的好处。

OpenAPI 规范

OpenAPI 规范 (OAS) 是一种 与供应商无关 的 HTTP 基远程 API 描述格式。它最初基于 Swagger 2.0 规范，由 SmartBear Software 于 2015 年捐赠。

目前，OAS 由 OpenAPI Initiative (OAI) 维护、发展和推广，OAI 是一个行业专家联盟，在 Linux 基金会旗下拥有开放的治理结构。这意味着所有会议和决定都是公开的，任何人都可以提出和讨论 OAS 的更改。

这种开放性鼓励了大量工具的创建（例如，看看 OpenAPI 工具列表），这些工具完美地展示了开放的机器可读 API 描述（如 OAD）的强大功能。

这可能是因为在使用 OpenAPI 时可用的工具数量如此之多，以至于它已成为 描述现代 API 的最广泛采用的行业标准。

还需要说明的是，OAS 的目标不是能够描述 所有可能的 API，因为这样做需要一个相当庞大且笨重的规范。相反，它试图 有效地描述最常见的用例。尽管如此，OpenAPI 提供的好处是如此之多，以至于通常值得设计您的 API，以便可以使用 OAS 完全描述它。

如果您的 API 的某些部分无法使用 OAS 描述，并且无法重新设计，则仍然可以将其从 OAD 中排除：OpenAPI 列出了可以执行的操作，但它没有断言关于 OAD 中不存在的操作的任何内容。

最后，OpenAPI 可以描述基于 HTTP 协议的 API（如 RESTful API），还可以描述基于 类似 HTTP 的协议 的 API，如 CoAP（受限应用程序协议）或 WebSockets。这使得 OpenAPI 可以在资源受限的情况下使用，例如物联网 (IoT)。

随时跳转到下一章，OpenAPI 规范解释，开始学习如何使用 OAS。或者停留更长时间，通过比较本地和远程 API 描述的演变来获得历史视角。

简要的历史比较

机器可读的 API 描述并非新鲜事物，它们在本地 API 中已经存在很长时间了：例如，C 具有方法签名，而像 Java 或 C# 这样的高级语言具有接口定义。本页中显示的远程 API 描述完全是为了相同的目的，本节应让更熟悉传统本地 API 的读者更清楚地了解此目的。

在计算机科学的黎明时期，只存在 汇编语言。在这种语言中，要调用另一个开发人员提供的方法，您需要使用约定的格式将参数写入约定的内存地址，然后将程序控制权转移到另一个约定的内存地址。最终，控制权将返回到您的程序，您可以从另一个约定的内存地址检索任何结果。

如您所见，需要达成很多协议，所有这些协议都必须正确 记录。在任何这些项目中发生错误或误解，在编写代码时是无法检测到的，并且会导致从程序故障到系统崩溃的运行时问题。

幸运的是，创建了更高级的语言，它们除了其他功能外，还提供了 方法签名。这些签名是代码的一部分，因此是 机器可读 的，允许在编译时检测不匹配：API 提供方发布其所有方法的签名，而消费者的编译器确保 API 正确使用（在一定程度上超过了文档本身）。

后来，互联网出现了，随之而来的是 **远程 API**。例如，基于 HTTP 的 API 向服务器请求特定资源，并期望响应包含特定格式的信息。最初，所有这些都是通过文档来指定的，**汇编语言中存在的问题** 再次出现，即如果请求格式与服务器期望的不符，则无法正常工作，并且在编译时无法检测到错误。

为了使远程 API 拥有与本地 API 方法签名相同的稳健性，人们发明了 **机器可读的 API 描述（包括 OpenAPI）**。现在已经存在一些工具可以检查请求是否以正确的格式发出，甚至可以通过自身生成请求代码来确保这一点。

机器可读的远程 API 描述带来的好处远超方法签名的作用。例如，OpenAPI 可以将示例和注释附加到大多数 API 部分，以补充自动生成的文档，或者重用描述的一部分以使整个文件更加简洁。

在下一章 OpenAPI 规范详解 中，了解所有这些功能以及更多内容。