kinlane

由 Postman 首席布道师 Kin Lane 和 OpenAPI Initiative (OAI) 业务治理委员会 (BGB) 联席主席撰写

我最近与GitHub 的员工开发人员 Marc-André Giroux 就他们的 OpenAPI 之旅进行了座谈，以了解这个社交编码平台如何在整个 API 生命周期中使用 OpenAPI。GitHub 在任何类型的软件开发中都扮演着核心角色，并且在整个 API 生命周期中也处于核心地位，但该平台的 API 在如何提供 API 基础设施规模方面提供了丰富的经验教训。因此，我们很荣幸能就 GitHub 正在进行的 OpenAPI 之旅进行讨论，并将此愿景与 OAS 社区分享。

您何时开始使用 OpenAPI 规范的旅程？

GitHub 于 2019 年开始研究 OpenAPI。有趣的是，两个团队独立地开始研究它，这突出了 OpenAPI 如何为用户带来诸多好处。一方面，我们的文档团队希望获得一个机器可读的文档，从中生成他们的文档。另一方面，API 团队（我所在的团队）希望将 OpenAPI 用作 API 开发体验的核心部分。例如，拥有设计优先流程、请求验证、契约测试、代码风格检查等。

我们的文档团队首先开始探索 OpenAPI。他们巧妙地从**我们手写的文档**生成了初始文档。这是一个很好的开始，但从我们 API 团队的角度来看，由于它是从我们无法完全信任的东西生成的，因此我们团队认为必须对这个 OpenAPI 描述进行测试，并由我们的运行时代码使用它，以确保它既准确又完整。

在 2020 年上半年，我们与文档团队合作，利用他们的初始工作，将其迁移到 API 的代码库中，并在验证中间件中使用它，该中间件将告诉我们任何不匹配之处。我们构建了自动修复错误的工具，手动修复了许多错误，并且在 2020 年 7 月，我们已准备好发布我们 OpenAPI 描述的测试版。

目前哪些团队在您的组织内部使用 OpenAPI？

我们 API 的覆盖面非常广。几乎每个在 GitHub 上开发功能的团队最终都会为其编写一个 API。这意味着最终，大量不同的团队会与 OpenAPI 进行交互。作为 API 团队，我们也认为这些团队是我们的客户。我们确保他们使用 OpenAPI 的体验很棒，并且我们拥有合适的工具来帮助他们构建出色的 API。我们的文档团队还使用 OpenAPI 生成我们大多数 API 文档网站。

OpenAPI 用于公共 API 吗？内部 API？还是两者兼而有之？

OpenAPI 目前仅用于我们的公共 API。我们有很多内部 API，我们最终希望用 OpenAPI 来描述它们。但是，我们最近切换到使用Twirp 作为大多数内部用例，它由 Protobufs 描述。

您能详细介绍 OpenAPI 如何在不同领域中使用吗？

文档

我们的开发人员编写的 OpenAPI 会自动与我们的文档存储库同步。我们的文档团队构建了一个很棒的管道，进一步装饰 OpenAPI，并用于呈现我们的API 文档。

代码生成

我们还在我们的开源存储库中同步 OpenAPI 描述。这是我们第一个代码生成用例 Octokit JS SDK 使用的。Gregor Martynus 做了很棒的工作，使用我们发布的 OpenAPI 来生成 TypeScript 类型并为 JavaScript SDK 提供支持。

很快，我们也希望帮助我们自己的开发人员进行代码生成。我们已经在运行时利用 OpenAPI 操作来配置某些资源，但我们希望进一步推进它，并帮助从 OpenAPI 操作生成实现。

测试

GitHub 的 API 实现在一个巨大的 Ruby 单体架构中，拥有成千上万个现有测试。我们通过在 API 的现有集成测试套件中包含自定义 OpenAPI 验证中间件来利用这一点。这种契约测试对于我们对 OpenAPI 文档准确性的信心至关重要，并且是我们 OpenAPI 工作中最难也是最重要的一部分。

许多现有的 OpenAPI 验证器返回的错误不一定对用户友好。我们花费了大量时间来提出一种抽象，使我们能够返回面向开发人员或面向最终用户的错误。例如，作为集成测试一部分返回的 OpenAPI 验证错误会返回错误消息，指示开发人员错误发生的原因以及如何修复它。在请求验证方面，我们改为指示用户输入无效的原因以及如何更正它。

促使您采用 OpenAPI 的因素是什么？

虽然生成文档是一个极好的好处，但对我们来说，OpenAPI 不仅仅是这些。启用强大的工具并构建出色的开发人员体验是我们关注 OpenAPI 的主要原因。

您是否为用户提供 OpenAPI 副本供下载？如果是，您在哪里提供它？

是的！如前所述，我们已将其作为开源存储库提供，位于此处。

您目前是否正在使用或已在您的操作中建立任何 OpenAPI 扩展？

我们在操作的“生命周期”的不同阶段使用了相当多的扩展。我们支持 GitHub REST API 的许多不同版本。我们的经典公共 API，以及每个版本的 GitHub Enterprise。虽然 API 类似，但它们在不同版本之间确实存在差异。我们没有复制每个操作和组件，而是选择了一个构建系统，该系统允许我们用版本信息注释 OpenAPI 对象。例如，我们有一个 `x-github-releases` 扩展，允许开发人员从某些版本中包含或排除操作。此扩展未出现在我们发布的描述中，因为它会被该构建系统剥离。

我们还有其他公共扩展，它们会向某些 OpenAPI 对象添加一些 GitHub 特定的元数据。例如，我们有一个名为 `x-github-previews` 的扩展，它会告知此操作是否为API 预览的一部分。

其他扩展在我们的开源存储库中进行了描述。

您的团队是否加入了技术开发人员社区的对话以发展 OpenAPI 规范？

目前还没有，但最近的叠加规范讨论引起了我们的极大兴趣。我们很可能会很快加入这些对话。

您是否使用其他 API 规范（例如 AsyncAPI、GraphQL、gRPC）？如果是，您能否分享原因的详细信息？

是的！我们使用 GraphQL 作为另一个公共 API，它为 GitHub 的领域提供了不同的体验，并为我们的客户提供了更灵活的用例（更多信息请参见此处）。如前所述，我们还在我们的内部Twirp API 中使用 Protobuf。

您如何说服您组织的领导层 OpenAPI 是一项重要的投资？

幸运的是，领导层已经开始使用机器可读的文档来描述我们的 API。我们已经广泛使用 JSON 超级模式，但 OpenAPI 在社区中的快速采用以及它如何使我们能够准确地描述我们的 API 使我们最终选择了 OpenAPI。

结论

GitHub 对 OpenAPI 的采用遵循了我们与其他领先的 API 提供商（如 Salesforce、Twitter、Plaid 等）看到的类似趋势。多个团队正在认识到使用 OpenAPI 的好处，文档是首要驱动因素，然后是代码生成和测试分别位居第二和第三。在其旅程中更进一步的 API 提供商已经意识到 OAS 并不总是能完全满足他们的需求，并且像 GitHub 一样，正在扩展规范并越来越多地转向参与每周的技术开发人员社区电话会议，以帮助发展规范。看到像 Github 这样的领先提供商认识到并开始利用 OpenAPI 规范 (OAS) 的业务优势，我们感到欣慰，我们期待他们更多地参与社区。
如果您想分享您的 OpenAPI 之旅故事，我们很乐意听取您的意见。虽然 Plaid、GitHub 和其他 API 提供商的故事之间的许多细节相似，但从多个视角和业务领域讲述故事会有所帮助。如果您有想分享的 OpenAPI 故事，请随时提交 GitHub 问题，并附上您的想法，我们将考虑将其添加到编辑队列中。我们要感谢 GitHub 和 Marc-André Giroux 让我们采访他们，并将这个精彩的故事与 OpenAPI 社区分享。感谢 GitHub 为我们提供了另一个例子，说明为什么 GitHub 在 21 世纪技术交付方面处于领先地位。