OpenAPI vs RAML vs API Blueprint，谁是最后的赢家？

API设计之战早已解决。但偶尔有人会问： “我应该使用RAML，还是应该使用OpenAPI？”如果您的团队不使用MuleSoft的网关，您可能从未听说过RAML。同样，如果您的团队在Oracle中不使用Apiary，您可能不熟悉API Blueprint。本文重温了十多年前开始的API设计小规模冲突，并探索了这些格式现在的地位。

API设计之战

在2010年代初的API设计战争中，规范格式与行业主导地位作斗争。当尘埃落定时，三种格式成为有前途的竞争者：API Blueprint、RAML和Swagger（后来更名为OpenAPI）。

API蓝图是一种用于生成文档的标记格式。它于2013年由Apiary开发，后被甲骨文收购。
RAML代表RESTful API建模语言，是一种API设计格式，由MuleSoft于2013年开发，后被Salesforce收购。
Swagger是一种API描述格式，由Wordnik于2010年开发，后被SmartBear收购。它后来更名为OpenAPI，并捐赠给Linux基金会。

OpenAPI赢得了战争

2015年，几家知名公司联合成立了Linux基金会的OpenAPI倡议，为API规范制定通用标准。标准化API的设计和记录方式使它们更容易维护、采用和使用。

Apiary最终于2016年加入该倡议，MuleSoft于2017年效仿。今天，除了自己的格式外，两家公司还支持OpenAPI。这些象征性的举动向规范社区的其他成员表明，他们愿意为整个API生态系统的利益进行合作。这种合作逐渐扩展到各个团队和公司，大家以一致和可预测的方式设计API。

2023年，当人们谈论以设计为主导的API优先方法时，OpenAPI在很大程度上是使用最广泛的规范格式。在Postman的API状态报告中，OpenAPI 2.0（又名Swagger 2.0）和OpenAPI 3.x是最广泛采用的API规范，39%至55%的受访者使用每个版本。而RAML和API蓝图采用率均为7%。

为什么OpenAPI赢得了战争？

OpenAPI（当时名为Swagger）首先上市，但还有其他一些关键因素有助于通过口碑迅速传播：

开源生态系统：Swagger、RAML和API Blueprint都是开源项目。然而，Swagger吹捧了开源工具、代码生成和客户端SDK的丰富生态系统，使社区能够更有机地增长。API社区仍然可以通过为围绕标准的开源软件做出贡献来支持Swagger，即使他们没有直接为开源标准本身做出贡献。相比之下，工具提供商是RAML和API蓝图格式提供商的竞争对手，这使得他们对支持竞争对手的格式犹豫不决。
工具不可知论者：Swagger在一家API公司Wordnik孵化，因此标准是工具不可知论者。相比之下，RAML和API蓝图是由API工具开发的，这意味着RAML和API蓝图的早期用户需要考虑未来的供应商锁定。

OpenAPI是更好的格式吗？

毫无疑问，OpenAPI是使用最广泛的标准。然而，RAML和API蓝图都解决了合法问题，通常以更有针对性的方式。

例如，考虑OAS和RAML之间的差异。2017年，MuleSoft表示：“RAML已成为建模API规范的主要方式，[OpenAPI]已成为描述API的最常见格式。”

使用这些术语时有相似之处和模糊之处。如果我们要求ChatGPT告诉我们“建模”和“描述”API之间的区别，它告诉我们，“API建模是指设计和定义API结构的过程，包括其端点、请求/响应格式和错误处理。它涉及创建API功能和行为的蓝图。另一方面，API描述是指记录API的行为，包括其目的、使用和参考信息，如可用的端点、请求/响应格式、身份验证方法和错误代码。API描述的目的是为开发人员提供有效使用API所需的所有信息。”

总之，API建模是关于设计API，而API描述是关于记录它。
ChatGPT，由OpenAI开发的聊天机器人

换句话说，开发 RAML 是为了对 API 进行建模和设计，而开发 Swagger 是为了描述和记录 API。在 API 生命周期的初期，当 API 生产者决定 API 应该是什么时，他们可能会倾向于使用 RAML。API 生产者可能会在设计完成后生成 Swagger 文件，以增强 API 消费者的开发体验。无论意图如何，这两种格式都可用于在整个 API 生命周期中对 API 进行建模或描述。

事实上，随着 OpenAPI 的广泛应用，API 生产者现在使用这种格式来设计和记录他们的 API，我们也看到了一些 API 优先的实施方案。与其他替代方案相比，API 消费者对 OpenAPI 也更为熟悉。因此，争论每种标准的优劣已经没有意义，因为 OpenAPI 已经赢得了这场战争。