随着最近发布的 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（基础设施即服务）：这次是完整的虚拟机，您可以对部署和扩展的环境进行更多控制。
在我的例子中，我使用使用 Apache Groovy 编程语言（还有什么？:-) 实现的容器化 Ratpack 实现来实现我的 API。因此，我在 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 规范相互兼容的工具和解决方案。