原文链接：https://document360.com/blog/open-api
OpenAPI 是什么？
根据SmartBear（Swagger的母公司）：
“OpenAPI规范（OAS）定义了一个标准、与语言无关的接口，用于 RESTful API，允许人类和计算机在没有访问源代码、文档或通过网络流量检查的情况下发现和理解服务的能力。”
这有点拗口。让我们将 SmartBear 的描述分解成较小的部分：
1.“...定义了一个标准...”：
OpenAPI规范定义了 API 的结构，也描述了 API。
2.“...与语言无关的接口到 RESTful API...”：
- REST API 使用 HTTP 协议进行数据传输。该协议允许使用不同编程语言编写的平台和系统进行交互。
- OpenAPI 仅处理 RESTful API，而不是其他类型的 API。
3.“...允许人类和计算机发现和理解服务的能力...”：
- 人类可以直接再 API 的 OAS 定义生成的文档中进行阅读。
- 客户端基于 API 定义了解如何发送请求以及 API 服务器如何响应这些请求。
4.“...无需访问源代码、文档或通过网络流量检查。”
使用 OpenAPI，客户端应用程序和 API 服务器是分开的。服务的 API 定义定义了客户端如何与之交互，而无需客户端阅读其源代码。
总结来说，OpenAPI 是一个 RESTful API 规范，描述符合 RESTful 架构的 API。规范提供了一个接口，让人类和计算机理解 API 以及如何与之交互。
OpenAPI的历史
OpenAPI 的起源可以追溯到 2009 年，当时 Wordnik 公司的工程师 Tony Tam 创建了一个规范（当时称为 Swagger），用于描述 Wordnik 的在线字典 JSON API。
在接下来的几年里，Tony 对 Swagger 进行了几次迭代。然而，Swagger 2.0 规范的采用率增加，并触发了解析规范的工具的创建。
2015年，SmartBear 收购了 Swagger。SmartBear 是当前拥有 Swagger的公司。Swagger 规范被重命名为“OpenAPI”，以反映新的 OpenAPI 倡议。这就是为什么“Swagger”与“OpenAPI”标准混淆的原因。
当时，一群公司认识到，行业需要一种供应商中立和标准化的方式来描述API。行业需要为行业提供“最佳实践”并监督 OpenAPI 的更新。
这些公司在 Linux 基金会下建立了 OpenAPI 倡议，作为一个治理程序，维护 OpenAPI标准并提供实际指导。成立 OpenAPI 倡议的创始公司包括 CapitalOne、PayPal、SmartBear、IBM、3Scale、Google、Apigee、Intuit、Microsoft 和 Restlet。从那之后，参与该倡议的公司数量已大幅增长。
技术指导委员会现在管理 OpenAPI，并根据社区反馈继续发布新版本。
为什么 OpenAPI 是一个流行的标准？
有几种规范可用于描述 RESTful API。OpenAPI 是其中最知名和广泛使用的规范。我们稍后将介绍 OpenAPI 的优势和劣势与其他格式的比较。虽然 OpenAPI可以被认为是行业标准，但最终公司通常会选择最适合其业务需求的格式。
那么如果有多种格式都可以用于描述 REST API，为什么 OpenAPI 显得如此特别？OpenAPI 之所以如此受欢迎的一个关键因素是其采用率。更多的采用导致更多的社区支持、强大的工具和更有效的治理。
公司可能会因其可移植性和简单性而使用 OpenAPI 规范。OpenAPI 是 “与语言无关的”，并为客户端-服务器通信定义了一种共同语言。它与使用不同编程语言编写的系统高度兼容。OpenAPI 对人类和计算机都具有很高的可读性，并且得到了一个庞大且不断增长的社区的支持。
另一种流行的格式是 RAML，这是一种 API 建模语言，专注于 API 定义和设计（尽管您可以使用 OpenAPI 设计 API ）。RAML 的功能可能看起来比 OpenAPI 更优越。它具有层次结构和支持数据模型继承的优势。然而，RAML 的采用率不如 OpenAPI 广泛。虽然 RAML 有一个专门的社区，但它的社区支持较少。RAML 有工具，但有一些迹象表明最新版本缺乏必要的支持。
除了 RAML，API Blueprint 是 OpenAPI 的另一个替代品。API Blueprint 专注于清晰的文档，依赖于 markdown 格式，而不是像 OpenAPI 一样的 JSON 或像 OpenAPI和 RAML一样的YAML。由于采用率低，API Blueprint缺乏社区支持和强大的工具。将 API Blueprint 集成到您的整个 API 生命周期中是困难的，因为它的主要重点是文档。
总结来说，OpenAPI 是描述 API 的最流行标准。尽管它有缺点，但 OpenAPI 的采用率可能会增长，而其他规范类型的长期可行性是不确定的。
OpenAPI 如何定义 API？
想象一下，你正在阅读一个 Microsoft Word（.docx）格式的传统规范文档。这份传统规范文档提供了系统的广泛背景，并描述了其组件以及与其他系统的交互。
传统规范的结构往往各不相同。而像 OpenAPI 这样的API规范，其结构是严格的。如果API规范符合另一种格式，如 RAML 或 API Blueprint，那么该文档将遵循该格式的结构。
回到 OpenAPI 如何定义 API 的问题上，你经常会听到“规范”和“定义”这两个词被当作同义词使用。API 规范“定义”了一个 API。在阅读 API 规范时，你会了解到可以发送的请求类型以及期望从 API 接收到的响应。此外，规范还描述了影响返回信息的可用选项。就像传统规范一样，你可以了解一个系统、其组件以及交互方式。
传统规范和 API 规范之间的另一个区别是，API 规范是动态的。每当 API 的底层源代码发生变化时，文档就会更新。而每当系统发生变化时，传统规范文档则需要手动更新 Word 文档。
OpenAPI 的格式
在了解 OpenAPI 规范的结构之前，你必须了解 OpenAPI 文档的格式。与传统的 Word 编写的规范不同，OpenAPI 的格式是 JSON。虽然讨论 JSON 的细微差别超出了本博客文章的范围，但可以把 JSON 看作是一种将API数据表示为键值对的方式。
例如，在传统规范中，你会在封面页上使用标题样式来编写规范的标题（包括系统名称）。另一方面，要编写 OpenAPI 规范的标题，你会将标题写为 JSON 键值对。
现在，想想关于 API 的所有信息。它的方法、操作、响应等。想象一下所有这些属性都按照 OpenAP I结构记录在一系列这样的键值对中。
注：虽然 JSON 是 OpenAP I的标准格式，但也可以使用更简单的 YAML（YAML不是标记语言的缩写）来表示 OpenAPI。
- 注意： 然 JSON 是 OpenAPI 的标准格式，但也可以将 OpenAPI 表示为更简单的 YAML（YAML ain’t markup language 的缩写）。
数据类型
作为一个 JSON 对象，OpenAPI 规范支持更广泛的JSON模式规范中定义的数据类型。基本数据类型包括整数、数字、布尔值和字符串。你可以使用修饰符属性 format 来声明数据类型的格式。例如，你可以将整数声明为 int32 或i nt64 格式，将数字声明为 float 或 double，或将字符串声明为 binary、 data、 date-time或 password 格式。OpenAPI 还支持在更广泛的 JSON 规范中定义为模式对象的模型（对象）。
重要的是要注意，JSON 是 REST API 用于发送和接收信息的主要格式。
结构
到目前为止，我们了解到：
- OpenAPI 规范是一个 JSON 对象。
- API 的属性是一组键值对。
- 值是由更广泛的 JSON 规范定义的数据类型。
现在是时候讨论 OpenAPI 的结构了。正如前面提到的，OpenAPI 文档是严格结构化的。相关键值对以对象或对象数组的形式分组。OpenAPI 规范的高级对象就像传统规范文档中的章节。
下面是一个带有折叠部分的 OpenAPI模板，显示了整体结构。每个部分都有属性或键值对，提供有关 API 的元数据。
OpenAPI 的顶层，由第一组括号 { } 表示，称为“文档对象”，因为它包含所有OpenAPI 属性。
虽然 OpenAPI 文档必须符合基本结构，但 OpenAPI 提供了一些灵活性。一些高级部分是必需的，而其他部分则不是必需的。你会注意到不同 API 的 OpenAPI 规范可能看起来略有不同。
OpenAPI 文档可能包含以下组成部分：
- Openapi： 一个必需字段，定义 API 的 OpenAPI 规范版本。工具使用版本号解析OpenAPI 规范以生成文档，例如。
- Info： 个包含元数据的必需字段。工具可以以不同的方式利用元数据。
- Servers： 个服务器对象数组。每个服务器对象包含连接到服务器的详细信息。该对象包含服务器主机的URL和服务器的描述。
- Paths： 一个必需对象，包含API各个端点的相对路径。给定路径有可用于与 API 交互的操作，如 POST、GET、PUT 或 DELETE。
- Components： 一个包含请求体、响应模式和安全方案的可复用模式的对象。此部分中的模式在规范的某些部分（如路径对象）中使用 $ref 标签引用。
- Security： 一个声明授权请求的安全方案类型的对象。安全对象是全局定义的，也可以精确指定去（安全方案覆盖）覆盖。
- Tags： 包含元数据的对象。解析规范的工具可以利用这个对象。例如，你可以指定你希望每个 API 资源在 API 文档中显示的顺序（而不是按字母顺序）。
- ExternalDocs： 提供指向附加文档链接的对象。你可以使用这个对象添加到你的用户指南的链接。
模式
在 API 文档的底部，通常有一个模式部分，对应于 API 定义中组件部分描述的模式。
这部分是一个快速参考，当读者需要在API的更广泛上下文中查看一般模式（而不是它们在特定操作中的使用）时。模式是包含属性/元数据的对象。
以下是 Swagger Petstore 的模式部分，显示了规范范围内的模式。Order 是一个模式，代表在 Swagger Petstore 下为宠物下的订单。每个订单都有其元数据，包括其ID、发货日期和订单状态。
OpenAPI 的优势
OpenAPI 具有以下优点：
- 清晰的文档?– OpenAPI 以其易于人类和计算机阅读的文档而闻名。
- 语言无关?– 客户端可以在不了解服务器实现的情况下与API服务器交互。其他格式，如 API Blueprint，需要服务器上的第三方代码，并且不为你提供任何此代码。
- 治理?– OpenAPI 倡议维护 OpenAPI 标准，并由行业领导者主持。
- 广泛采用?– OpenAPI 是描述 REST API 的最流行格式。其采用范围表明 OpenAPI 是长期的。像 API Blueprint 这样的规范因缺乏采用而受苦。
- 强大的工具?– 作为最广泛支持的格式，现在有大量工具利用 OpenAPI 生成文档、测试等。其他规范缺乏 OpenAPI 的支持和工具维护。
OpenAPI 的劣势
每种规范类型都有其优点和缺点。在这里，我们将重点介绍 OpenAPI 与其最接近的竞争对手 RAML 相比的劣势。
对 API 设计和规划不太有用
你可以采取“规范优先”的方法来设计基于 OpenAPI 的 API。这种方法涉及手动编写 API 的 OpenAPI 规范或使用设计工具。使用这种方法，你设计 API 的规范，然后在构建 API 时将规范作为“合同”。与“规范优先”相反的是，使用 OpenAPI 生成文档，但并不将其作为设计工具。
虽然“规范优先”的方法有许多优点，但 OpenAPI 通常不会在 API 开发之前出现。
RAML 的层次结构可能更适合作为设计和规划工具。因此，RAML 可能比 REST 更支持 “规范优先” 的方法。最终，RAML 被营销一种为了 “数据建模” 和 “API 描述” 工具，而Swagger 则仅是后者。下一节将更详细地讨论 RAML 的层次模型。
非层次化
OpenAPI 和 RAML 等 API 定义标准的核心概念之一是能够创建数据对象并将它们关联在一起。OpenAPI 使用模式来实现这一点，并支持 JSON 的内置数据类型。RAML使用一个类型系统来保存相关属性并促进规范之间的重用。它还支持与 OpenAPI 相同的内置数据类型。
OpenAPI 并没有真正的层次结构。你希望从描述你的 API 的层次结构中得到什么？理想情况下，你希望有一个关联你的数据模型的系统，这个系统应该是：
- 易于阅读/理解
- 允许使用继承在数据模型之间定义关系
- 减少共享属性的重复
- 最大化代码重用
与 REST 相比，RAML 的类型系统使其成为一个更加层次化的系统。根据 RAML 在GitHub 上的自述，RAML 使用 “资源类型和特征最小化了 RESTful API 设计中的重复，并促进了 API 内部和跨 API 的一致性。”
接下来我们将更详细地讨论 RAML 的类型系统。
不支持数据模型继承
RAML 的对象类型可以继承其他对象类型。虽然 OpenAPI 模式可以“引用”其他模式，但它并不像 RAML 那样在技术上支持继承。我说“技术上”是因为你可以使用一个模式引用（$ref标签）将一个模式链接到另一个模式。
而 RAML 则更进一步。你可以在数据模型之间建立关系，并避免共享属性的重复。使用 OpenAPI，模式不会像 RAML 那样以层次化的方式相互关联。RAML 类型具有“真正”的继承性，你可以在其中建立数据模型之间的父子关系。
非“可视化”工具
RAML 将类型作为数据模型，使其比 OpenAPI 更直观、更易于阅读。你可以很容易地看到类型及其共享属性之间的关系
作为一个更视觉化的工具，RAML促进了对诸如模拟服务器响应、API控制台等的长期规划。它也可能有助于使用RAML预测和规划未来的API改进。
缺乏对其他架构的支持
OpenAPI 只能描述 RESTful API。RAML 具有支持除 REST 之外的其他架构的额外支持，如 RPC 或 SOAP，只要它们使用 HTTP 协议。RAML 的灵活性允许你将其用于除 REST 之外的架构的文档工具。
OpenAPI 示例 - Swagger Petstore
学习 OpenAPI 最好方法是就是实践。有些工具允许你编辑 OpenAPI 规范，然后生成API 文档。Swagger Petstore 是 OpenAPI 文档的一个示例。
SwaggerUI 是一个用于解析 API 定义生成文档的工具。SwaggerUI 有基于浏览器的编辑器（如下所示）。你可以在这里尝试 SwaggerUI 编辑器：https://editor.swagger.io/
在左侧面板上，可以看到 YAML 格式的 OpenAPI 规范。当你对规范进行更改时，这些更改都会在右侧面板中生成新的文档。右侧面板是直接从左侧面板的 OpenAPI 规范（Swagger Petstore）生成的 Swagger 文档。例如更改路径的描述会导致 Swagger文档刷新以显示新更改。
如果你查看 Swagger 的 OpenAPI 规范左侧，你将看到本文中描述的所有部分，包括openapi, info, servers, paths, components, tags等。
当你输入错误的 OpenAPI 结构或输入无效内容时，Swagger 会报错。Swagger 的错误处理强化了你必须遵守 OpenAPI 格式以正确显示文档的概念。一旦你熟悉了Swagger Petstore，你可以将其他的 API 的规范粘贴到 Swagger 编辑器中，看看它的信息如何在 SwaggerUI 中显示。
总结来说，Swagger 编辑器是了解如何编写 API 定义以及工具如何解析规范以生成文档的好方法。
进一步阅读
要深入了解OpenAPI 标准，请阅读官方 SmartBear 的 OpenAPI 文档：https://swagger.io/specification
更多 API 管理及 API 全生命周期相关内容可以在我的 Notion 查看，我将会持续更新：API 全生命周期管理资料
