技术文章

对于提供公共服务的组织来说，确保最终用户能够访问最新版本可能具有挑战性，特别是如果公司的工程文化允许团队频繁部署的话。HubSpot 曾经就是这种情况。在 HubSpot 与 Postman 合作之前，HubSpot 公共 API和 Postman Collections 没有得到很好的维护或易于访问，这导致社区沮丧和开发人员体验不佳。

为了解决这些问题，HubSpot 的 API 工具和开发人员倡导团队联手。他们的共同努力促成了GitHub和 Postman 之间的集成，允许 HubSpot 使用 GitHub 在其Postman 工作区中发布和管理其 API 定义。

将 HubSpot 的公共 API 定义整合到单个存储库中，消除了不断跟踪架构更改和更新 Postman 工作区（其中包括 40 多种服务）的手动工作。

在这篇博文中，我们将指导您完成此集成过程，并演示您需要采取哪些步骤来确保您的 GitHub 存储库是您的 Postman 工作区的真实来源。

将您的 API 模式与 GitHub 和 Postman 集成

在开始之前，确保您的规范使用 OpenAPI 3.0 非常重要。如果您使用的是 2.0 版本 (Swagger)，您可以使用Swagger 提供的 REST 端点进行转换，也可以使用Swagger 编辑器：

第 1 步：将 API 架构上传到 GitHub 存储库

将所有 API 架构文件上传并提交到您为创建 API 而设置的 GitHub 存储库。最好清楚地命名文件并具有可区分的目录结构，以便您在构建 API 时可以轻松区分它们并选择正确的文件。

我们 HubSpot 做了类似的事情：我们有自己的 GitHub 存储库，其中保存公共 API 的所有定义。您可以在这里查看。

步骤 2：将 API 架构更新与 Postman 中的 API 同步

首先通过从 Github 存储库导入其架构文件来创建新的 API。这个初始步骤对于构建监控其定义更新的 API 至关重要。为此，请单击在 Postman 中创建新 API ，然后选择GitHub 存储库选项。这可确保 Postman 中的 API 与 GitHub 中相应的架构文件之间的无缝集成：

接下来，使用 API 架构文件选项选择用于创建 API 的API 架构文件：

根据同一 GitHub 分支中的规范创建多个 API 时，请确保不要将集合目录选项留空。相反，请在导入 API 定义的位置创建一个新目录。然后，使用这个新路径作为您的集合目录路径。

注意：如果您在设置第一个 API 时选择默认集合目录 (postman/collections)，则在创建后续 API 时将会遇到错误。此问题强调了在 GitHub 存储库中拥有组织良好且独特的目录结构的重要性：

您现在已准备好为每个 API 生成可分叉集合。只需单击 API 名称并导航到“集合”选项即可从导入的架构生成集合：

这就是创建可以自动跟踪 API 架构更新的 API 所需的全部内容。但是，您如何知道定义文件何时更新，例如何时添加新端点或何时架构文件属性更改？

将您的 API 链接到 GitHub 存储库后，Postman 将在 UI 中通知您 API 定义文件的任何更改：

当您提取这些更改时，Postman 会通知您集合的任何更新。例如，在这篇博文中，我使用新端点更新了架构：

查看您的更新并更新您的收藏：

第三步：向外部消费者发布API

集合的更新由工作区管理员管理。发布版本化 API 允许外部使用者访问最新的集合。

在发布之前，您必须将 Postman 为跟踪 API 操作而创建的所有文件提交到 GitHub。Postman 要求在允许 API 发布之前提交所有更改：

现在是发布 API 的时候了，它使用户能够将集合分叉到他们的工作区。为此，请通过单击 API 名称导航至“发布 API”选项：

然后您将能够看到最新版本的列表：

步骤 4：发布包含最新更新的新 API 版本（可选）

最终消费者将看到 API 发布时的集合快照。对原始 API 定义文件的更新不会自动反映在使用者工作区的分叉集合中。

但是，工作区管理员可以发布具有更新版本号的新版本 API。然后，消费者可以选择使用这些新版本更新他们的分叉集合：

为此，消费者必须确保在分叉集合时勾选“观察原始集合”复选框：

然后，消费者可以通过单击“拉取更改”选项将其集合更新到最新发布的版本：