随着最近宣布的 OpenAPI 规范 v3，现在是时候暂停一下，思考一下使用 API 契约来描述您的 Web API 的好处。通过开放且免费访问的、计算机友好的格式，它为工具、兼容性或团队协作提供了非常重要的视角，并培养了富有成果的生态系统。
使用 OpenAPI 规范 (OAS) 描述 API 的好处
简而言之，API 契约是真相的来源。无论您是实现 API 后端的人，还是调用 API 的使用者，都存在这样一个中心契约，双方都可以依赖它，以确保 API 的外观、预期类型的端点、将交换的有效负载或使用的状态代码。
通过中心契约，团队沟通和协作得到促进：我见过一些客户，其中一个中央架构团队会定义一个契约，由第三方（外包咨询公司）实施，而 API 由不同的团队（内部和外部）使用。中心契约在这里是为了促进这些团队之间的工作，确保契约得到履行。
此外，拥有这样一个计算机友好的契约对于工具而言非常有用。根据契约，您可以生成各种有用的工件，例如
- 静态和实时模拟 - 当 API 尚未完成时，使用者可以使用这些模拟，
- 测试存根 - 用于促进集成测试，
- 服务器骨架 - 使用现成的项目模板开始实现 API 的业务逻辑，
- 客户端 SDK - 为使用者提供工具包，可以使用各种语言更轻松地调用您的 API，
- 沙箱和实时游乐场 - 一个用于测试和调用 API 的可视化环境，供开发人员发现 API 的实际工作方式，
- 具有预配功能的 API 门户 - 一个提供 API 参考文档并允许开发人员获取访问 API 凭据的网站，
- 静态文档 - 也许只有 API 参考文档，或者是一捆有用的相关用户指南等。
但是，要小心工件生成。一旦您开始对工具生成的工件进行一些自定义，您可能会在下次重新生成这些工件时冒着覆盖这些更改的风险！因此，请注意如何进行自定义以及如何将其与这些生成的工件集成。
关于扩展基于 OpenAPI 规范的 Web API 的演示
InfoQ 最近发布了去年在巴黎举行的 APIDays 会议的视频。我谈到了使用 Google Cloud Platform 上的 Cloud Endpoints 扩展基于 OpenAPI 规范的 Web API。
我谈论过这个主题几次，因为 Web API 是我喜欢的主题，在 Nordic APIs、APIDays 或 Devoxx 上都谈过。但很高兴看到 视频上线。所以让我分享幻灯片以及视频。
您也可以查看下面嵌入的幻灯片。
在我的演示和演示中，我决定使用 Cloud Endpoints 来管理我的 API，并在 Google Cloud Platform 上托管我的 API 实现的业务逻辑。GCP（简称）为您的项目提供了各种“计算”解决方案
- Google App Engine（平台即服务）：您部署代码，平台会为您透明地完成所有扩展，
- Google Container Engine（容器即服务）：它是一个基于 Kubernetes 的容器编排器，您可以在其中以容器的形式部署应用程序，
- Google Compute Engine（基础设施即服务）：这次是完整的虚拟机，您可以对部署和扩展的环境进行更多控制。
在我的例子中，我使用容器化的 Ratpack 实现来实现我的 API，并使用 Apache Groovy 编程语言（还有什么？:-)）。因此，我在 Container Engine 上部署了我的应用程序。
我通过 OpenAPI 描述符描述了我的 Web API，并通过 Cloud Endpoints 进行管理。Cloud Endpoints 实际上是 Google 本身用于托管开发人员今天可以使用的所有 API 的底层基础设施（例如 Google Maps API 等）。此架构每天实际上已经服务了数千亿个请求……因此，您可以假设它本身肯定非常可扩展。您可以管理使用 OpenAPI 描述的 API，而不管它们是如何实现的（与底层实现完全无关），它可以管理基于 HTTP 的 JSON Web API 以及 gRPC API。
无论您是将平台用于公共/私有/移动/微服务 API，都有三个有趣的关键方面需要了解 Cloud Endpoints
- Cloud Endpoints 负责安全，控制对 API 的访问，对使用者进行身份验证（利用 API 密钥、Firebase 身份验证、Auth0、JSON Web 令牌）
- Cloud Endpoints 提供关键 API 相关指标的日志记录和监控功能
- Cloud Endpoints 非常快速，并且如前所述可以很好地扩展（我们将在稍后详细介绍）
Cloud Endpoints 实际上提供了一个开源的“边车”容器代理。您的容器化应用程序将与可扩展服务代理携手并进，实际上将被该代理包装。所有调用实际上都将通过该代理才能到达您自己的应用程序。有趣的是，并非只有一个代理，而是您的每个应用程序实例都将拥有自己的代理，从而减少了对代理的调用与应用程序中实际代码执行之间的延迟（这两者之间没有网络跳跃，到某个距离较远的中央代理，因为这两个容器在一起）。顺便说一句，此代理基于 Nginx。并且该代理容器也可以在其他地方运行，甚至在您自己的基础设施上运行。
总结
总之，Cloud Endpoints 负责保护、监控和扩展您的 Web API。在 Google Cloud Platform 上开发、部署和管理您的 API 为您提供了选择：在协议方面，使用基于 JSON/HTTP 的 API 或 gRPC，在实现技术方面，您可以选择平台支持的任何语言或框架，使您可以从 PaaS 迁移到 CaaS 或 IaaS。最后但并非最不重要的是，此解决方案是开放的：基于 OpenAPI 和 gRPC 等开放标准，或通过在 Nginx 之上实现其代理。
通过像 OpenAPI 规范这样的开放格式来描述 API，所有与 API 相关的利益相关者都可以协同工作并获得以下好处。
首先，团队更容易有效地协同工作，因为所有成员都可以依靠 API 描述作为代表 API 外观的真相。当一个团队设计契约，而另一个团队（可能是外部团队）实施契约时，尤其如此。有一个描述 API 的真相来源，可以简化团队中的沟通。
其次，作为一个计算机友好且经过良好规范的格式，可以自动化各种任务，例如生成模拟、客户端库、服务器骨架等。您还可以使用该规范来检查实现是否符合契约。
最后，通过开放且免费访问的格式，供应商、开源项目和开发人员的生态系统可以协同工作，防止锁定效应，允许 API 开发人员利用通过 OpenAPI 规范相互兼容的工具和解决方案。