作者：Kin Lane，Postman 首席布道师，OpenAPI Initiative (OAI) 商业治理委员会 (BGB) 联席主席
我最近与 GitHub 的员工开发人员 Marc-André Giroux 坐在一起，了解他们的 OpenAPI 之旅，以了解更多关于社交编码平台如何在整个 API 生命周期中使用 OpenAPI 的信息。GitHub 在任何类型的软件开发中都发挥着核心作用，并且在整个 API 生命周期中也处于核心位置，但该平台的 API 在提供 API 基础设施规模方面提供了丰富的学习经验。因此，我们很荣幸能够就 GitHub 所处的 OpenAPI 之旅进行此次讨论，并将这种愿景与 OAS 社区分享。
您何时开始使用 OpenAPI 规范？
GitHub 在 2019 年开始研究 OpenAPI。有趣的是，两个团队独立地开始研究它，这突出了 OpenAPI 如何为 API 表格带来许多不同的好处。一方面，我们的文档团队希望拥有一个机器可读的文档，从中可以生成他们的文档。另一方面，API 团队（我所在的团队）希望将 OpenAPI 用作我们 API 开发体验的核心内容。例如，拥有设计优先流程、请求验证、契约测试、代码检查等。
我们的文档团队首先开始探索 OpenAPI。他们巧妙地从我们的手写文档中生成了一个初始文档。这是一个很好的开端，但从我们 API 团队的角度来看，由于它是从我们无法完全信任的东西中生成的，因此我们对这个 OpenAPI 描述至关重要，它正在针对我们的运行时代码进行测试，并由我们的运行时代码使用，以确保它既准确又完整。
在 2020 年上半年，我们与文档团队合作，使用他们的初始工作，将其移植到 API 的代码库中，并在验证中间件中使用它，该中间件会告诉我们任何不匹配的地方。我们构建了工具来自动修复错误，手动修复了许多错误，并在 2020 年 7 月，我们已经准备好 发布我们的 OpenAPI 描述的 beta 版本。
目前哪些团队在您的组织中使用 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 企业版。虽然这些 API 类似，但它们在不同版本之间确实存在差异。为了避免重复每个操作和组件，我们选择了一种构建系统，允许我们在 OpenAPI 对象上添加版本信息注释。例如，我们有一个 `x-github-releases` 扩展，允许开发人员从特定版本中包含或排除操作。这个扩展不在我们发布的描述中，因为它会被构建系统剥离。
我们还有其他公共扩展，将一些 GitHub 特定的元数据添加到某些 OpenAPI 对象中。例如，我们有一个名为 `x-github-previews` 的扩展，它会告知此操作是否属于 API 预览。
其他扩展在 我们的开源代码库中描述。
你们的团队是否加入了技术开发者社区的对话，以推动 OpenAPI 规范的发展？
目前还没有，但最近的叠加规范讨论引起了我们极大的兴趣。我们很可能会很快加入这些讨论。
你们是否使用其他 API 规范（例如 AsyncAPI、GraphQL、gRPC）？如果是，你能分享一下原因吗？
我们使用！我们使用 GraphQL 作为另一个公共 API，它为 GitHub 的领域提供了不同的体验，并为我们的客户提供了更灵活的使用场景 (更多信息在这里)。正如之前提到的，我们还使用 Protobuf 用于我们内部的 Twirp API。
你们是如何说服组织中的领导层，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 世纪技术交付方式方面处于领先地位。
