本文是对即将在Codemotion 大会（西班牙马德里，11 月 24 日）上发表的“使用 OpenAPI 规范设计 API”的演讲的简短预览。
我们作为开发者，被强大的、令人惊叹的 API 所包围。仅仅为了寻找时间来集成这些有趣的服务以增强我们的产品，可能是一项艰巨的任务，仅仅因为时间是我们开发者最稀缺的资源。
API 集成是开发者的一个反复出现的问题，因为我们经常会感到自己像沮丧的管道工一样，试图连接不同尺寸和材料的管道，被迫一遍又一遍地创建自定义适配器和连接点。你已经知道这种感觉了吧？
我们已经生活在一个 API 经济推动技术创新的快速时代。亚马逊、Paypal、Stripe、Heroku 和 Google Maps 等平台只是成功平台和产品的几个例子，它们在各自的市场上处于领先地位，并在其周围创建生态系统。如果你拥有生态系统，你就能赢得比赛。API 有一个故事要讲：好的 API——易于第三方使用——可以帮助进一步推广。我们作为 API 使用者，在很多情况下决定了哪些 API 会成功，哪些 API 会被弃用。
在这种快速创新的背景下，API 发现和轻松集成是城里每项新服务的关键。这就是 OpenAPI 规范最能发挥作用的地方。
OpenAPI 规范为描述基于资源和 HTTP 的可互操作 REST API 提供了一个可靠的标准。这种描述对两种类型的受众很有用：人类和机器。
- 人类使用规范作为 API 文档的来源，作为示例，以及作为尝试和理解 API 功能的指南。易用性是这里成功的关键因素。
- 机器使用规范来创建能够以你的开发语言与服务协议通信的代码。以这种方式减少了前面描述的繁重的管道工作，并最大限度地减少了对平台特定 SDK 的成本和需求。
根据我的经验，在你的 API 项目中使用 OpenAPI 规范有三种主要用例：遗留 API、契约优先驱动和服务器优先驱动。让我们逐一审查它们。
1. 遗留 API
第一种场景涵盖了已经投入生产的服务和 API。添加 OpenAPI 文档将以标准化的方式正式捕获 API 的签名。因此，使用者可以使用此契约作为文档，轻松地与你的 API 集成。
只要你使用 HTTP 或 HTTPS 以及 JSON 或 XML 编码，无论你选择使用哪种语言或框架来实现，都没有关系：你有一个可互操作的 API 等待着全世界发现。
这里最令人惊讶的是：你无需更改正在运行的 API 或服务的一行代码。OpenAPI 规范提供的元数据是一个存储在自包含文件（YAML 或 JSON）中的契约，你可以离线（作为文件）共享或发布在任何 Web 服务器上。
添加契约不会改变你的遗留实现的一行代码，但会帮助那里的开发者尝试和使用你的 API。
2. 契约优先驱动 API
为了加快开发速度，经常会在两个团队（后端和前端）之间并行工作。如果他们同意一个 API 契约，他们就可以并行构建自己的东西。前端人员通常会创建和使用契约的模拟，以便能够在后端准备就绪之前工作。
OpenAPI 和相关工具在这里提供了良好的工具。OpenAPI 契约可以在没有任何语言或实现假设的情况下进行编辑和验证（使 API 非常、非常可互操作）。
然后，使用 OAS 代码生成工具，这两个团队可以在任何支持的语言或平台上为服务器端生成框架，为前端生成代理。
我建议在主要功能足够清晰以能够提前设计契约时采用这种工作方式。
从长远来看，你将以计划的方式维护和发展契约。因此，这是从长远来看实现高质量 API 契约的推荐方法。
注意：为了避免在出现新版本时破坏旧客户端，明确的版本控制策略很重要。
3. 服务器优先驱动 API
在其他类型的项目中，开发者可以选择直接在他们最喜欢的语言和平台上构建他们的 API，并在以后作为运行实现的直接结果导出 API 契约。这种场景也得到了 OpenAPI 规范的支持。使用特定于目标语言的库。使用反射技术和元数据来发现服务、类型、参数，直接检查源代码以自动生成符合 OAS 标准的规范。
这种方法有一些优点
- 自动生成的文档和契约。
- 契约始终与服务实现同步。
- 服务器端开发的敏捷性。
这种方法的主要缺点
- 在发展服务时要谨慎，因为你可能无意中破坏了现有的客户端。
- 派生的契约可能缺乏简洁性或 UX（与契约优先相比）。为自动化优化的内容可能对人类来说令人困惑：为人类设计。
注意：我建议在需求和设计快速变化并且你的团队正在迭代寻找合适的契约设计时采用服务器优先方法。因为还没有投入生产，这将减轻破坏客户端的问题。无论如何，在发布之前，请完全审查你的最终 API 契约，并重构以获得更好的 UX。
结论
OpenAPI 提供了一种可互操作的方式来描述 API
- 正式到足以被机器使用，并且
- 简单到足以被开发者用来记录和学习 API。
描述的三种场景提供了灵活性，以适应不同的项目需求。老实说，我认为这是 OpenAPI 的前身（称为 Swagger）从一开始就做对了的主要功能：很好地适应了非常不同的开发场景和不同的项目开发阶段。
与管道工程或电气工程相比，软件工程仍然是一门年轻的学科。我们需要帮助我们处理和自动化重复性任务的标准。这就是为什么我认为无论你是机器还是人类，使用 OpenAPI 规范公开 API 都是一件好事！
如果你喜欢这篇文章，并想了解更多信息，请加入我在 11 月 24 日在马德里举办的 Codemotion 大会上的演讲，让我们深入探讨吧！
关于作者
Pedro J. Molina
Pedro J. Molina 拥有瓦伦西亚理工大学计算机科学博士学位。在不同产品公司（与建模和代码生成相关）工作之后，他创建了一家名为 Metadev 的初创公司，专注于微服务和云开发的工具。推特：@pmolinam