作者：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 团队（我所在的团队）希望将 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 Enterprise。虽然 API 类似，但它们在不同版本之间确实存在差异。我们没有复制每个操作和组件，而是选择了一个构建系统，该系统允许我们在 OpenAPI 对象上添加版本信息注释。例如，我们有一个 `x-github-releases` 扩展，允许开发人员从某些版本中包含或排除操作。此扩展不在我们发布的描述中，因为它会被该构建系统剥离。
我们还有其他公共扩展，它们会向一些 OpenAPI 对象添加一些特定于 GitHub 的元数据。例如，我们有一个名为 `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 并不总是能满足他们 100% 的需求，并且像 GitHub 一样，正在扩展规范，并越来越多地转向参与每周的技术开发人员社区电话会议，以帮助改进规范。看到像 GitHub 这样的领先提供商认识到并开始利用 OpenAPI 规范 (OAS) 的业务优势，我们感到欣慰，我们期待着他们更多地参与到社区中来。
如果您想分享您的 OpenAPI 之旅故事，我们很乐意听到您的分享。虽然 Plaid、GitHub 和其他 API 提供商的故事之间许多细节相似，但从多个角度和业务领域讲述故事是有帮助的。如果您有 OpenAPI 故事想要分享，请随时 提交一个 GitHub 问题，并附上您的想法，我们会考虑将其添加到编辑队列中。我们要感谢 GitHub 和 Marc-André Giroux 接受我们的采访，并与 OpenAPI 社区分享这个精彩的故事。感谢 GitHub 为我们提供另一个例子，说明为什么 GitHub 在 21 世纪技术交付方面是领导者。