本文是对即将在西班牙马德里举行的 Codemotion 会议（11 月 24 日）上发表的演讲“使用 OpenAPI 规范设计 API”的简短预览。
我们作为开发者，被强大的、令人惊叹的 API 所包围。仅仅是抽出时间来集成这些有趣的服务以增强我们的产品可能是一项艰巨的任务，仅仅因为**时间**是我们开发者最稀缺的资源。
API 集成对于开发者来说是一个反复出现的难题，因为我们经常感觉自己像沮丧的管道工，试图连接不同尺寸和材料的管道，被迫一遍又一遍地创建自定义适配器和连接点。你已经知道这种感觉了，不是吗？
我们已经生活在一个快速发展的时代，API 经济推动着大部分技术创新。像亚马逊、PayPal、Stripe、Heroku 和谷歌地图（仅举几例）这样的平台都是各自市场上成功的平台和产品的良好例子，它们在其周围创造了生态系统。如果你拥有生态系统，你就能赢得游戏。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 规范的规范。
这种方法有一些优点
- 自动生成的文档和契约。
- 契约始终与服务实现同步。
- 服务器端开发的敏捷性。
该方法的主要缺点
- 在发展服务时要勤勉，您可能会无意中破坏现有客户端。
- 派生的契约可能缺乏简单性或用户体验（如果与契约优先相比）。针对自动化进行优化可能会让人类感到困惑：为人类设计。
注意：当需求和设计快速变化并且您的团队正在迭代以找到正确的契约设计时，我推荐服务器优先方法。尚未投入生产，这将减轻破坏客户端的问题。无论如何，在启动最终的 API 契约之前，请完整审查您的最终 API 契约并进行重构以获得更好的用户体验。
结论
OpenAPI 提供了一种描述 API 的互操作方式
- 足够正式，可以被机器使用，并且
- 足够简单，可以供开发人员使用以记录和学习 API。
所描述的三个场景提供了灵活的功能以适应不同的项目需求。老实说，我认为这是 OpenAPI 前身（称为 Swagger）从一开始就做对的主要功能：很好地适应非常不同的开发场景和不同的项目开发阶段。
如果与管道或电气工程相比，软件工程仍然是一门年轻的学科。我们需要帮助我们处理和自动化重复性任务的标准。因此，我认为无论您是机器还是人类，使用 OpenAPI 规范公开 API 都是一件好事！
如果您喜欢这篇文章并想了解更多信息，请加入我在 11 月 24 日在马德里举行的 Codemotion 上的演讲，让我们深入探讨它！
关于作者
Pedro J. Molina
Pedro J. Molina 拥有瓦伦西亚理工大学的计算机科学博士学位。在不同的产品公司从事建模和代码生成相关工作后，他创建了一家名为 Metadev 的初创公司，专注于微服务和云开发工具。推特：@pmolinam