企业如何从 OpenAPI 规范中受益

如今，客户愈发依赖于数字产品和服务，企业家也意识到了投资商业软件应用程序的重要性。

应用程序编程接口（API） 就是这样一个例子。API 通过软件中介连接两个应用程序，并允许这两个软件产品相互交换数据或“通信”。这是可能的，因为 API 中有两个组件：

1. 描述数据交换条件的技术规范

2. 为遵循该规范而编写的软件界面。

当这两个组件协同工作时，它们可以实现各种交易，帮助企业完成核心业务流程。这些包括登录、产品搜索、与不同支付平台的在线交易等。

有能力的 API 开发人员会编写、记录和测试 API 的函数调用，这些函数调用是允许软件执行独特操作和服务的语言语句。为了使 API 设计过程尽可能顺利地进行，API 开发人员需要有一个好的工具集供他们使用。相反，精明的企业家深知一个优质的API及其工具集能够带来怎样的不同凡响的影响。设计特别精良的 API 产品可以促进他们与客户的互动，并增加他们对品牌的好感。因此，API开发人员与客户企业之间建立起比以往任何时候都更加牢固的合作伙伴关系，也就不足为奇了。

也就是说，重要的是要认识到，仅仅将资金投入API开发本身，并非是获取更高利润的绝对保障或唯一解决方案。方向的选择、API 开发的工具和设计方法也很重要。这就是为什么当今以技术为导向的一代企业家不仅应该学习 API，还应该学习 OpenAPI 规范（OAS）格式。如果您是企业主，那么拥有此类技术会让您受益。

以下是对 OpenAPI 规范、其历史以及 API 开发人员和客户业务的优缺点的更深入讨论，这些利弊将受到使用描述格式的影响。在这里，您可以了解以 OpenAPI 为中心的团队和企业运行完整的 API 工具包的价值。最后，您将阅读一些真实示例，了解来自多个行业的企业如何调整以变得更加 API 驱动。这有助于您直观地理解，采用以OpenAPI为中心的方法可能会给您的组织带来哪些影响。希望额外的知识将赋予您的企业更加现代的优势。

OpenAPI 规范：基本概念回顾

什么是 API 规范？

首先，让我们讨论规范对 API 设计的重要性。在 API 设计中，该规范旨在标准化两个 Web 服务之间的数据交换。开发人员依靠规范来了解 API 产品的确切行为方式以及它如何与其他 API 链接。这一规范应当能够支持各种与API相关的技术协同工作，不论这些技术是基于何种编程语言开发的。

话虽如此，开发人员可以将其 API 产品用于多种类型的 API 规范。在 2000 年代初期，API 世界中占主导地位的描述格式是服务对象访问协议（SOAP）和 Web API 描述语言（WADL）。但如今，被称为OpenAPI规范的，已成为REST API或使用具象状态传输（RESTful）架构风格的Web API的“行业标准”。

什么是 OpenAPI 规范，它与其他 API 规范有何不同？

OpenAPI 规范（简称 OAS）是 Tony Tam 的创意，Tony Tam 是一家名为 Wordnik 的在线词典服务的技术联合创始人。它最初在 2009 年创建时被称为 Swagger 规范，用于描述 Wordnik 的 JavaScript 对象表示法（JSON） API。该规范的使用对 Wordnik 中的 API 文档、服务器集成和代码生成任务有很大帮助。

当其他开发人员开始将该格式用于他们自己的 API 时，Tam 寻求正式化 Swagger 规范。它于 2015 年被信息技术公司 SmartBear Software 采用;然后在 2017 年，它由一个名为 OpenAPI Initiative 的开放治理组织更名并投入运营。在撰写本文时，OAS 目前的版本为 3.0.3，其事实来源目前位于软件存储库 GitHub 上。

OAS 区别于其他规范的值得注意的特征是：

它提供了一个标准且与语言无关的接口来描述 RESTful API。
它既是机器可读的，又是人类读者可以解释的。
OAS 的机器和人类消费者都可以理解正在开发的服务的功能，即使无法访问后者的源代码、网络流量或任何其他文档。

这些特性为OAS带来了巨大的优势，即消费者即便在只掌握最少实现逻辑的情况下，也能够理解并远程服务进行交互。使用 OAS 描述其 REST API 的开发人员将受益于 API 设计过程中更加清晰的内容。这是他们为客户构建适应性强、可靠且易于使用的 API 所需的垫脚石。

开发人员和客户企业应该如何考虑 OpenAPI 规范？

开发人员和客户企业都希望在做出有关格式的任何决策之前评估 OAS 的优缺点。让我们来看看 OAS 在 API 开发和业务方面的优缺点。

OAS 对 API 开发人员的优缺点

以下是 OAS 为 API 开发人员提供的一些主要优势。

熟悉和协作的 API 开发。 在 API 行业，默默无闻是没有好处的。行业最佳实践的协作性和统一性越强，对实际从业者就越有利。API开发人员在OAS的开源环境中十分幸运，因为找到有关该规范及其使用方法的最新知识并不困难。这些知识也来自 API 行业的顶级人才，他们非常愿意提高其他开发人员使用该格式的技能。这种共享的生产力对当今 API 的整体质量非常重要。

稳定实施的机会高。 由于 OAS 拥有强大的开源社区和跟踪记录，因此可以稳定地实施到新开发人员的 API 设计工作流程中。OAS 是一种广泛使用的技术，其支持者将长期使用该技术，并且在不久的将来，该规范被放弃或与其他解决方案合并的可能性很小。

API 测试的可靠事实来源和标准。 未经广泛测试的 API 产品将给客户业务及其客户带来灾难。考虑到这一点，API 开发人员将需要一个规范来帮助他们更好地测试滞后和错误。它可以帮助开发人员将 OAS 纳入其设计工作流程中。如果 OAS 是 API 的单一事实来源，则开发人员可以更轻松地根据规范测试 API 系统的所有部分。反过来，这增加了他们交付优质 API 产品的机会。

一种生成 API 文档的方法。 最后，OAS 可以帮助编译美观且交互式的 API 文档，或详细说明 API 工作原理的技术内容可交付成果。API 文档是开发人员和 API 客户端都迫切需要的东西。API文档的作用远超过普通说明手册——它不仅是指导用户如何使用API产品的指南，还是推销其强大功能的工具。一些托管工具集可以从现有的 OpenAPI 定义自动生成 API 文档。如果你自己的 API 团队使用这样的工具集，你将能够生成具有专业外观的文档，从而提高 API 的可行性。

然而，由于没有技术是绝对完美或万无一失的，而且使用 OAS 有一些缺点，开发人员不应忽视。考虑以下最明显的缺点。

学习曲线。 OAS 与语言无关，使用该规范不需要开发人员仅仅为了使用不同的编程语言编写代码而向后弯腰。但这并不意味着它可以在瞬间学会。要熟练使用 OAS，开发人员仍然需要调整他们的工作流程，并使用与 OAS 相关的所有资源来定位自己。

成为创可贴 API 设计解决方案的危险。 初学者或经验较少的开发人员可能犯的最大错误之一，就是误以为OAS是创建最终产品的万能良药。OAS 并不是以架构为中心的 API 设计的创可贴解决方案，因为 API 设计需要更具体的补救措施。如果 OAS 更多地被用作理解 API 的捷径方法，那么它就违背了使用规范来发布全面、精心设计的产品的目的。

OAS 对客户业务的利弊

企业主可以预期 OAS 的使用会产生涓滴效应，从 API 开发人员开始，到 API 的客户端结束。以下是 OAS 驱动的 API 设计框架可以为客户业务提供的几件事。

客户业务可以期待设计良好的 API 产品。 要理解 OpenAPI 规范对 API 客户端的价值，应该将它们视为模型车、飞机或玩具机器人的购买者。这些产品附带蓝图或组装指南，用于说明哪个部件放在哪里。当玩具公司制作的指南为消费者提供清晰、直接和全面的组装说明时，它会增加他们根据正确规格成功构建模型的机会。OAS 的效果与客户端 API 的规范相同。基于同样的理由，它使客户业务成为更好的 API 产品的接收端。

客户端和 API 开发人员通过 API 协定获得参考点。 对于任何需要客户和提供商之间合作的产品，双方必须达成一致。必须有一个参考点，以便双方了解产品应该实现什么、它是如何工作的以及预期的潜在问题。从这个意义上说，OAS 不仅仅是一种描述格式。它为 API 协定提供了基础，在该协定中，每个人都清楚 API 是如何设计的以及它将如何执行。这对于那些想要确认该产品是否物有所值的客户企业而言，无疑会让他们感到十分欣慰。

当然，客户企业应该考虑一些关于 OpenAPI 规范的小注意事项，包括以下问题。

需要花时间解释 OpenAPI 规范的基本原理。 如果 OAS 是一个复杂的框架，API 开发人员需要理解，那么不了解该技术的客户业务呢？API 开发人员不应忘记，与 API 行业的外部人士讨论 OAS 可能会导致一些信息过载。

这并不是客户应该了解的唯一 API 元素。 API 设计是一个非常复杂的过程，涉及几个方面。对于开发人员或客户来说，在衡量产品的最终性能时专注于 OAS 都是不好的。

尽管有些不足之处，但OpenAPI规范仍然是一项极具发展潜力的技术。许多 API 开发人员都从将其整合到他们的工作流程中受益。当然，与这些开发人员签订 API 产品合同的企业主是主要受益者。

现代企业如何从 OpenAPI 规范的使用中受益：一些现实生活中的例子

现在，您已经对 OpenAPI 规范的特性有了更多的了解，您可能希望了解此类技术如何应用于现实生活。事实上，来自几个关键行业的许多企业可能已经部署了 OAS 驱动的 API。这些 API 产品目前正在帮助他们实现核心业务功能，并以更大的能力服务于他们的市场。

以下是对三个行业如何欢迎 OpenAPI 规范并将 OAS 驱动的 API 用于重要任务的研究。您一定会认出下面提到的品牌名称。

电子商务

电子商务行业是 OpenAPI 技术的最大受益者之一。OAS 是电子商务店主可以如此快速扩展其服务并在此过程中让要求苛刻的客户满意的原因之一。世界顶级的电子商务平台，如 BigCommerce，也非常有利于使用开源软件进行设计。这意味着，对于大多数在电子商务API中采用OAS的API设计人员而言，实现设计框架往往并非难事。

如果您想了解如何在大型电子商务应用程序中使用 OAS 的另一个示例，您只需查看在线竞价网站 eBay 即可。eBay 使用 OAS 向感兴趣的开发人员提供 API 合同。这些合同可以作为将使用 eBay API 的新应用程序的参考点。因此，电子商务是设计 OAS 驱动的 API 最令人兴奋的领域之一 – 电子商务企业家是受益者。

媒体

OpenAPI 规范也常用于媒体行业的 API。它主要为 API 做出贡献，这些 API 以快速、易于理解和有效的方式向公众传播有价值的信息。在这种情况下如何使用 OAS 的一个例子是社交媒体巨头 Twitter 及其公共 API 开发人员平台。Twitter 的平台是使用 OAS 定义的，它提供了一系列公共 API，第三方网站和应用程序的开发人员可以自己使用。如果您访问的网站或博客使您能够通过 Twitter 共享信息，这一切都归功于这种 OpenAPI 驱动的机制。

可以说，OAS 有助于信息在专门的数字媒体以及拥有数字对应物的传统媒体（如大报）上传播。如今，人们主要通过互联网来消费本地和国际媒体，API和OAS肯定会继续存在并发挥作用。

银行和金融技术

银行业和金融科技行业是 OAS 实施的有趣案例研究。以前，使用公共 API 进行银行交易存在一些阻力，因为这些 API 可能对客户的安全构成威胁。但今天的 API 旨在更加安全，甚至更好地保护客户的私人信息。OAS 驱动的公共 API 现已赢得多家银行和金融机构的信任。这在所谓的“开放银行”的兴起中很明显，或者说通过开放 API 实现的通用银行服务的可用性。

从事开放银行相关服务的 API 设计人员可以求助于 OAS，以实施积极承认和断言事实等原则。这些只是 OAS 影响现代金融交易的一些方式，因为其影响力不断增长。最终可能会达到大多数金融服务将涉及使用 API 的地步。因此，最好对 API 在银行和金融中的使用有一些高级知识。