什么是 OpenAPI？
OpenAPI 规范 (OAS) 提供了一种一致的方式来在 API 生命周期中的每个阶段传递信息。它是一种用于 HTTP API 的规范语言，以一种不依赖于创建 API 的编程语言的方式定义结构和语法。API 规范通常以 YAML 或 JSON 编写，允许轻松共享和使用规范。
使用 OAS，您可以快速了解 API 的工作原理。由于它是与编程语言无关的，因此您可以快速识别和理解服务功能。您还可以使用 OAS 配置基础设施、生成客户端代码并为您的 API 创建测试用例。因此，OAS 可以支持您在整个 API 生命周期中的工作，并帮助您与组织内部和外部的开发者社区进行沟通。
什么是 OpenAPI？
能够向其他人（您的同事、您合作的企业或您提供 API 的组织）提供 API 的定义对于开展业务至关重要。API 经济的成功取决于重复、简洁和确定性地执行此操作，并使用与 API 消费者相关的语言。
API 规范语言提供了一种标准化的方法来执行此操作。您的 API 可以用与语言无关的术语来描述，将其与任何特定的编程语言解耦。您的 API 规范的使用者无需了解应用程序的内部结构，也不需要尝试学习 Lisp 或 Haskell（如果您选择用它们编写）。他们可以从您的 API 规范中理解他们所需的确切内容，该规范以简单且表达力强的语言编写。
OpenAPI 规范 (OAS) 正确实现了这种从 API 提供者到 API 使用者的知识转移。它是一种用于描述 API 的开放标准，允许您提供以 JSON 或 YAML 文档编码的 API 规范。它提供了一个全面的术语词典，反映了 API 世界中普遍理解的概念，并嵌入了 HTTP 和 JSON 的基础知识。当与支持工具结合使用时，它可以基于简单的文档提供丰富的体验。
API 生命周期中的 OAS
提供和使用 OAS 文档并不是一次性活动。它是 API 生命周期不可或缺的一部分，为从设计开始到部署和支持的所有活动提供支持。如果 API 生命周期是一个运输网络，那么 OAS 应该被视为一条主动脉道路，提供了一种快速有效地传输大量相关信息的方式。
当人们考虑 API 生命周期时，就会开始清楚 OpenAPI 文档有多么有用。考虑以下简单的 API 生命周期。它基于 API 优先设计的理念，即在不编写任何实现代码的情况下设计接口。OAS 可用于生命周期中的每个阶段。
组织内部的 API 生命周期显然比上面描述的步骤有更多的细微差别，并且无疑将针对正在使用的软件开发生命周期进行定制。例如，敏捷方法可能会多次迭代上面显示的步骤。但是，出于示例的目的，这种简化的视图具有价值，因为它显示了 OAS 在每个阶段的实用性。
使用 OAS 帮助收集需求
我们概念生命周期中的第一步是需求，在这个阶段，关于 API 的想法开始成形。“成形”涵盖了许多不同的活动——有些是技术性的，有些则不是。大多数组织中的需求收集会延伸到业务领域，与产品团队合作定义 API 应该为其消费者提供什么，并支持产品的整体功能视图。
从事满足这些需求的技术人员需要一些方法来传达它们。OAS 提供了一种以与语言无关且可移植的方式支持此操作的方法。它还提供了一种以快速的方式执行此操作并能够以最少的设置与其他利益相关者交流其想法的方法。
在收集需求时，如果在 OAS 中有一个 API 设计草图，那么在开始设计时就会有一个先机。
用于设计的 OAS
我们概念性 API 生命周期中的设计阶段是我们采用需求（在 OpenAPI 文档中勾勒出来或没有勾勒出来）并将其转化为有形的东西的阶段。无论您的起点是什么——一张空白的（虚拟）纸、代码库中存根和带注释的控制器类、您选择的图形设计工具中的图形表示——能够创建 OAS 供他人使用至关重要。鉴于我们的概念生命周期基于 API 优先设计，因此首选工具更有可能是 OpenAPI 编辑器或具有 OpenAPI 插件的 IDE。在大多数组织中，我们还可以添加许多工件来支持此活动：设计模式、基于行业标准的 Schema 对象、组织数据模型等等。
无论 API 提供者使用什么工具和工件，OAS 都提供了设计过程的有形输出。拥有一个定义明确且可版本化的工件至关重要，这对于 API 生命周期后续步骤的准确性和效率至关重要。一个 OpenAPI 文档（使用适当的机制进行源代码控制）允许以合理的方式发生这种情况，并为开发提供清晰明确的输入。
开发中的 OAS
一旦创建了 API 设计，就该编写一些代码并在软件中创建该 API 的实现。根据输出设计过程操作意味着使用 OpenAPI 文档来帮助使您的应用程序栩栩如生。
我们的概念生命周期假设了一种 API 优先的设计方法，其中 OpenAPI 文档是在预先创建的，然后编写代码来创建实现。当然，还有“代码优先”方法，其中创建实现，然后（通常）对其进行注释，以便可以生成 OpenAPI 文档。
两种方法的优缺点超出了本文的范围，但是，如果您采用 API 优先方法，那么在 OpenAPI 文档中详细说明设计对于您的实现至关重要。OAS 拥有丰富的工具生态系统，使用 OpenAPI 文档生成服务器端代码是自动创建控制器类的一种常见方法。这加快了实现的交付速度，并有助于确保接口设计和实现紧密匹配。
然而，在代码中实现您的 API 只是生命周期中的后续步骤之一。其他活动依赖于 OAS 才能成功完成。
使用 OAS 配置您的基础设施
绝大多数在内部或外部公开 API 的组织都使用基础设施来保护 API 免受恶意企图的侵害或提供标准化的部署模式。
API 管理可以说是这种情况下最常见的架构组件。其功能是保护 API 提供者的 API 并提供基于生命周期的功能，以帮助组织无缝地运营其 API。大多数 API 管理工具都支持使用 OpenAPI 文档作为配置的输入，使用它来构建（例如）API 网关配置，该配置观察 API 的结构并实现路径和参数验证、请求正文验证，并提供对与 API 功能关联的安全系统的调用。
这里的重点是效率。拥有 OpenAPI 文档来促进此过程，可以将其从冗长的配置练习转变为一键式操作。通过使用在设计时创建的相同工件，OAS 减少了 API 提供者的管理开销，所有这些都使用 OpenAPI 文档中表达的单个真相版本完成。
使用 OAS 创建开发人员体验
当我们谈论开发人员体验时，关于效率的观点也同样适用。能够通过与我们用于设计实现相同的方式与开发人员（公开或与合作伙伴、内部或外部）进行沟通，极大地加快了我们发布相关信息的方式。
许多开发人员只需要原始的 OpenAPI 文档在自己的工具中使用。显然，这是可用的——通常会用可以嵌入 OpenAPI 文档本身的书面文档进行修饰——但 API 提供者也可以通过他们自己的工具选择来提供丰富的开发人员体验。有无数与 OAS 兼容的工具可以一键式提供开发者门户、交互式体验来“尝试”提供者的 API 以及从 OpenAPI 文档生成的多种语言的软件开发工具包。
当然，OAS 本身无法完成所有工作。大多数 API 提供商都希望通过其产品和独特卖点的内容来创造身临其境的体验。这需要许多创意人士及其使用的工具的天赋。但是，OAS 提供了一个可以帮助将体验结合在一起的结构。
使用 OAS 进行测试
开发人员体验通常从 API 使用者的角度关注 OAS，作为 API 提供者提供的产品或服务的使用者。但是，还有其他使用者可以利用 OpenAPI 文档来了解 API 并执行与其相关的活动。
一个特别重要的领域是测试 API。API 提供商需要确保他们投放市场的 API 符合其可接受的质量和准确性水平。测试 API 需要与使用它相同的洞察力，因为需要了解结构、参数以及请求和响应定义。编写和执行测试用例需要与 API 使用者相同的理解水平。
API 测试是一个工具大量投资 OAS 作为输入的领域。例如，使用工具执行契约测试以检查设计和实现是否匹配是 API 提供者的一项常见活动。安全工具也是如此，它们会测试 API 占用空间以查找实现中的弱点。拥有 OpenAPI 文档提供了 API *应该*提供的定义，因此提供了可能无意中公开或实施安全实践薄弱的基线。
因此，测试是我们概念性 API 生命周期中的一个阶段，它显著受益于 OAS 的利用。使用 OpenAPI 文档作为输入既可以加速此活动，又可以提供执行测试的确定性机制。
💡 最终思考
我们 API 周期的最后一个阶段是关于使 API 可供 API 消费者使用。部署 API 显然不仅仅涵盖安装我们的软件实现。API 管理和开发者体验都需要结合起来，以提供 API 消费者想要提供的 API，为他们提供特定的产品或服务，以及他们需要了解其工作原理以及如何构建其软件的信息。
在本文中，我们试图解释 OAS 在将 API 提升到这一阶段的每个阶段中都非常有用。OAS 通过提供一种贯穿每个阶段的信息一致传递方式来将生命周期联系在一起。当正确完成时，OAS 为 API 提供者提供了一种宝贵的机制，以确保其工作的持续性和质量。
想要了解更多关于 OAS 的信息？请查看我们的OpenAPI 规范入门指南，以详细了解规范。另请访问我们的工具目录，其中提供了支持 OAS 的开源和商业工具的详细信息。