什么是开放API？优势、劣势与示例

什么是OpenAPI？

根据Swagger的母公司SmartBear的说法：

“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规范。该规范提供了一个接口，让人类和计算机都能理解API及其交互方式。

OpenAPI的历史

OpenAPI的起源可以追溯到2009年，当时Wordnik公司的工程师Tony Tam创建了一个规范（当时称为Swagger），用于描述Wordnik在线词典的JSON API。

在接下来的几年里，Tony对Swagger规范进行了多次迭代。Swagger 2.0版本显著提升了该规范的采用率，并催生了用于解析该规范的工具。

2015年，SmartBear收购了Swagger，目前该公司拥有Swagger。Swagger规范随后更名为“OpenAPI”，以体现新的OpenAPI倡议。这也是为什么“Swagger”常与“OpenAPI”标准相混淆的原因。

当时，一些公司认识到行业需要一个供应商中立且标准化的方式来描述API，需要为行业提供“最佳实践”，并持续监督OpenAPI的更新。

这些公司在Linux基金会下成立了OpenAPI倡议，作为一个治理项目，负责维护OpenAPI标准并提供实践指导。该倡议的创始公司包括CapitalOne、PayPal、SmartBear、IBM、3Scale、Google、Apigee、Intuit、Microsoft和Restlet。自那时起，参与该倡议的公司数量大幅增长。

目前，技术指导委员会负责管理OpenAPI，并持续根据社区反馈发布新版本。

有多种规范可用于描述 RESTful API。OpenAPI 是最知名且广泛使用的规范之一。用于 REST API 的另外两种格式是 RAML 和 API Blueprint。我们稍后将比较 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缺乏社区支持和针对OpenAPI的强大工具。将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规范的结构之前，您必须了解Open开发文档的格式。与用Word编写的遗留规范不同，OpenAPI的格式是JSON。虽然讨论JSON的细微差别超出了本文的范围，但您可以将JSON视为将API数据表示为键值对的一种方式。

例如，在遗留规范中，您会在封面页使用标题样式来编写规范的标题（包括系统名称）。另一方面，要编写OpenAPI规范的标题，您需要将标题写成一个JSON键值对。

现在，考虑一下关于API的所有信息。它的方法、操作、响应等等。想象一下，所有这些属性都按照OpenAPI结构记录在一系列这样的键值对中。

注意：虽然JSON是OpenAPI的标准格式，但也可以用更简单的YAML（YAML Ain't Markup Language的首字母缩写）来表示OpenAPI。

数据类型

作为JSON对象，OpenAPI规范支持更广泛的JSON模式规范中定义的数据类型。基本类型包括整数、数字、布尔值和字符串。您可以使用修饰符属性format来声明数据类型的格式。例如，您可以将整数声明为int32或int64格式，将数字声明为float或double格式，或将字符串声明为二进制、数据、日期时间或密码格式。OpenAPI也支持在更广泛的JSON规范中定义的模型（对象）作为模式对象。

值得注意的是，JSON是REST API用于发送和接收信息的主要格式。

💛🧡🧡客户评价：Baklib正在解决几个关键与文档和知识库管理相关的问题： -Baklib为我们提供了一个集中式知识库，简化了访问我们所有的技术文档、常见问题解答和用户指南。这已经改善了效率，并确保每个人都能获得最新的信息。 -随着我们公司的全球扩张，提供多个文档语言已经变得必不可少。Baklib的多语言支持使我们能够创建和管理各种语言的内容，制作我们的文档面向更广泛的受众，并支持我们的国际增长。

结构

到目前为止，我们了解到：

• OpenAPI规范是一个JSON对象。
• API的属性是一组键值对。
• 值是由更广泛的JSON规范定义的数据类型。

现在，是时候讨论OpenAPI的结构了。

如前所述，Open开发文档具有严格的结构。对象或对象数组将相关的键值对分组。OpenAPI规范的高级对象就像传统规范文档中的章节。

下面是一个折叠了章节以显示整体结构的OpenAPI模板。每个章节都有属性或键值对，提供关于API的元数据。

OpenAPI的顶层，由第一组大括号 { } 表示，被称为“文档对象”，因为它包含了所有OpenAPI属性。

尽管Open开发文档必须遵循基本结构，但OpenAPI提供了一定的灵活性。某些高级部分是必需的，而其他部分则不是。您会注意到不同API的OpenAPI规范可能看起来略有不同。

一个Open开发文档可能包含以下部分：

• Openapi – 一个必需的字段，用于定义API的OpenAPI规范版本。例如，工具使用版本号来解析OpenAPI规范以生成文档。
• Info – 一个必需的字段，包含元数据。工具可以以不同方式利用元数据。
• Servers – 服务器对象的数组。每个服务器对象包含到服务器的连接详细信息。此对象包含服务器主机的URL和服务器描述。
• Paths – 一个必需的对象，包含API各个端点的相对路径。给定的路径具有用于与API交互的可用操作，如POST、GET、PUT或DELETE。
• Components – 一个包含请求体、响应模式和安全性方案的可重用模式的对象。此部分中的模式在规范的某些部分（如路径对象）中使用$ref标签引用。
• Security – 一个声明授权请求的安全方案类型的对象。安全对象可以全局定义，也可以被单个操作覆盖（安全方案覆盖）。
• Tags – 一个包含元数据的对象。解析规范的工具可以利用此对象。例如，您可以指定每个API资源在开发文档中显示的期望顺序（而不是按字母顺序）。
• ExternalDocs – 一个提供指向额外文档链接的对象。您可以使用此对象添加指向用户指南的链接。

在您的开发文档底部，通常有一个“模式”部分，它对应于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的层次结构可能使其更适合作为设计和规划工具。因此，相比REST，RAML可能更支持“规范优先”的方法。最终，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 类型具有“真正的”继承，您可以在数据模型之间建立父子关系。

非“可视化”工具

与 OpenAPI 相比，RAML 使用类型作为数据模型使其更具可视化且更易于阅读。您可以轻松查看类型之间的关系及其共享属性。

作为一个更可视化的工具，RAML 促进了对模拟服务器响应、API 控制台等事物的长期规划。使用 RAML 可能还有助于预测和规划未来的 API 改进。

缺乏对其他架构的支持

OpenAPI 只能描述 RESTful API。除了 REST 之外，RAML 还有支持其他架构（如 RPC 或 SOAP）的额外优势，只要它们使用 HTTP 协议。RAML 的灵活性允许您将其用作除 REST 之外的其他架构的文档工具。

OpenAPI 示例 – Swagger Petstore

学习 OpenAPI 的最佳方式是亲自动手实践。某些工具允许您编辑 OpenAPI 规范，然后生成 API 文档。Swagger Petstore 规范就是一个 OpenAPI 文档的示例。

SwaggerUI 是一种解析 API 定义以生成文档的工具。SwaggerUI 有一个基于浏览器的编辑器（如下所示）。您可以在此处试用 SwaggerUI 编辑器：https://editor.swagger.io/

左侧面板中，可见YAML格式的OpenAPI规范。每当对规范进行更改时，这些更改都会在右侧面板中生成新的文档。右侧面板是由左侧面板的Petstore OpenAPI规范直接生成的Swagger文档。例如，更改路径的描述会导致Swagger文档刷新以显示新更改。

如果您查看左侧的Swagger OpenAPI规范，您将看到本文描述的所有部分，包括openapi、info、servers、paths、components、tags等。

当您偏离OpenAPI结构或输入无效内容时，Swagger会生成错误。Swagger的错误处理强化了这样一个概念：您必须遵守OpenAPI格式，文档才能正确显示。一旦您熟悉了Swagger Petstore，就可以将另一个API的规范粘贴到Swagger Editor中，以查看其信息如何在SwaggerUI中显示。

总之，Swagger Editor是熟悉如何编写API定义以及工具如何解析规范以生成文档的好方法。

有关OpenAPI标准的更深入文档，请阅读SmartBear官方的Open开发文档：https://swagger.io/specification/。

同时，也请查看我们关于发布公开API的指南。