版本控制 API

GitHub Enterprise Server、GitLab Self-Managed 和 Azure DevOps Server（托管在本地）集成仅适用于 Postman Enterprise 计划。

您可以管理在 Postman 中创建的任何 API 的多个版本。然后，您可以将模拟、监视器和文档与特定版本的 API 相关联。

API 版本控制不同于对集合使用版本控制。有关如何对集合使用版本控制的信息，请参阅使用版本控制。

版本控制概念

Postman 中的每个 API 都有一个或多个版本，并且版本有多个版本。每个版本也有一个状态。

  • 版本定义了 API的主要变体及其相关元素，例如文档、测试、模拟服务器和监视器。
  • 发布是对 API版本的定期增量更改。您可以在 Changelog 中查看已发布和未发布的更改，并在那里创建新版本。更改包括对 API 架构或任何相关元素的编辑。当您连接到外部 Git 存储库时，发布可以映射到 Git 发布标签。
  • 状态是一个文本标签，您可以更改它以指示 API 版本的当前开发阶段。

您可以并行创建任意数量的版本。例如，您可以创建一个新的 2.0 版本的 API 来引入新的重大更改并在内部进行处理，但继续向当前公开的 1.0 版本添加更改。

API优先开发的典型工作流程：

  1. 创建 API 的初始版本。设置版本的状态以指示它正在进行中，例如“计划中”或“开发中”。
  2. 更改架构和关联的集合。
  3. 查看更改日志中的更改。您可以在此阶段将 Postman 中的版本状态设置为“代码审查”或“安全审查”。
  4. 转到更改日志并选择Release changes。为发布命名，添加发布说明，然后创建发布。然后将状态更改为“生产中”。

使用外部 Git 存储库

您可以将 GitHub、Bitbucket、GitLab、GitLab Self-Managed 或 Azure DevOps 存储库连接到您的 API，并将您的 API 规范和关联的集合与存储库同步。您可以在 Postman 和 Git 中的开发分支之间不断地进行更改同步。

当发布时，您可以将开发分支合并到 Git 中的主分支，其中包含 API 的发布版本。然后，您可以创建一个 Git 版本，并将此版本标签映射到您在 Postman 中的版本。

使用外部 Git 存储库进行 API 优先开发的典型工作流程：

  1. 连接一个 repo 并设置一个开发分支。
  2. 在 Postman 中创建 API 的初始版本。设置版本的状态以指示它正在进行中，例如“计划中”或“开发中”。
  3. 在 Postman 中更改架构和关联的集合，然后将更改提交并推送到 Git 存储库中的开发分支。
  4. 您还可以使用其他工具或编辑器直接在 Git 中更改模式和集合。开发人员可以遵循 Git 工作流程，例如在功能分支上工作，然后创建 PR 以将它们合并到开发分支中。
  5. 定期从开发分支中拉取其他人对 Postman 所做的更改，并在有任何问题时解决冲突。
  6. 查看开发分支上的更改，然后将它们合并到 Git 中的主分支并创建 Git 版本。您可以在此阶段将 Postman 中的版本状态设置为“代码审查”或“安全审查”。
  7. 在 Postman 中，转到更改日志并选择Release changes。为发布命名，添加发布说明，并将发布映射到 Git 发布标签。然后将状态更改为“生产中”。

连接存储库

您可以在 API 级别将 API 连接到基于 Git 的远程存储库。这使您能够持续同步存储库和 Postman 之间的更改。然后在 Postman 和您的 Git 存储库之间同步版本和发布标签。

用于身份验证的用户帐户需要完全访问存储库。您可能希望专门为此集成创建具有有限权限的服务帐户。

您只能将一个 Postman API 连接到一个远程仓库。多个 API 需要多个存储库。一个 API 的多个版本可以链接到同一个 repo/branch 组合，只要开发只发生在一个分支上。如果您将存储库或分支链接到新版本，则该分支上的所有先前集成都将被锁定。对于非活动集成，不会发生拉取、推送或新的标签链接，但链接的标签将保留。

对于 GitHub 连接，目前 GitHub 对每个用户的每个应用程序施加了 10 个身份验证令牌的限制。如果您与同一用户创建超过十个连接，则额外的令牌将按照创建顺序被撤销。团队可以使用其他 Postman 帐户创建十多个集成。

要连接存储库：

  1. 在 API 版本页面上，选择Connect Repository并选择存储库类型：GitHub、GitHub Enterprise、Bitbucket、GitLab、GitLab Self-Managed或Azure DevOps。
  2. 将出现一个身份验证弹出窗口。输入信息以登录您的存储库并选择授予访问权限。

    您的浏览器可能会隐藏此弹出窗口。确保从该站点启用弹出窗口。

  3. 在连接您的存储库页面上，输入您的存储库的信息。
  4. 输入将存储 API的 Git组织和存储库。（对于 GitLab，Organization指的是Group，Repository指的是Project。）

    请注意，每个 repo 只能连接一个 Postman API。多个 API 需要多个存储库。

  5. 输入 API 的主分支。这用于获取发布标签；代码不会推送到此分支。
  6. 输入 API 的开发分支。这是推送代码更新的地方。
  7. 选择一个API 模式目录和集合目录，其中模式和集合将存储在 repo 中。如果您将值留空，则将在 repo 的根目录中创建一个postman/schemasor目录。postman/collections如果您选择一个已经包含架构的目录，您将在第一次拉取更改时被询问在 Postman 中使用哪个架构。
  8. 选择连接存储库。

如果您之前使用 GitHub 集成进行 API 模式的双向同步，则必须删除之前的集成才能将存储库连接到您的 API。现有集成将继续运行，但您无法将双向同步的新集成添加到 API 架构。

拉动和推动变化

当您连接到外部 Git 存储库时，存储库下拉列表会显示您当前的开发分支，并指示您在 Postman 中的 API 更改是在外部存储库中的文件之前还是之后。它显示了连接的分支和存储库的链接，以及最后一次将更改拉到 Postman 或推送到 Git 存储库的日期。它还包含用于拉取、提交和推送、切换分支和删除集成的命令。

API Builder 源代码控制

拉取更改

要从远程 repo 中获取更改，请从 repo 下拉列表中选择Pull 。这会将远程仓库的开发分支中的任何更改同步到 Postman。

如果您有与远程副本冲突的本地更改，您将看到一个指向最新 Git 提交和冲突文件的链接。

要解决冲突，请在每个文件旁边选择Keep remote file或Keep local file，然后选择Pull Changes。

第一次从远程仓库拉取更改时，如果远程架构目录已经包含架构文件，系统将提示您选择要在 Postman 中使用的架构。

提交和推动变更

要将本地更改添加到外部存储库，请从存储库下拉列表中选择提交并推送。您将看到已修改文件的列表。输入提交消息，然后选择Commit and Push Changes。

如果远程仓库有更改，您将被要求首先拉取更改。

切换分支

如果您的 Git 存储库有多个功能分支，您可以将 Postman 中的分支从开发分支切换到不同的功能分支。这使您能够在使用开发人员在不同功能分支中工作的 Git 工作流时查看和进行更改。

要切换到不同的分支，请在 repo 下拉列表中选择Switch Branch ，然后从列表中选择一个分支。请注意，仅当您的存储库除了主分支之外还有多个分支时，切换分支列表才可用。

当您不在配置的开发分支中时，您只能编辑 API 架构和集合。提交您的更改并将其推送到功能分支，然后在您的 Git 存储库中，您可以提出拉取请求、查看更改并合并回您的开发分支。

删除存储库连接

您可以随时删除与 Git 存储库的连接。如果您正在更改帐户或提供者，或者需要使用不同的开发分支，您可能需要这样做。

在 repo 下拉列表中，选择Delete Integration。请注意，这只会删除与 Git 的连接；它不会更改任何文件或分支。

使用 API 版本

当您在 Postman 中创建新 API 时，它还会创建您在 API 创建期间输入的初始版本。您可以从头开始或基于现有版本创建新版本。每个 API 版本都有自己的API 版本页面，您可以在 API 概览页面或左侧边栏中找到该页面。

创建版本

要创建 API 的新版本：

  1. 转到 API概述页面。选择三个点图标右上角的，然后选择创建版本。
  2. 输入版本名称。
  3. 如果您希望新版本可见，请选择使该版本可供消费者使用。否则，它只对编辑可见。
  4. 如果您希望此版本基于现有元素，请选择显示更多选项以展开对话框。在Copy elements from a previous version中，选择 API 的先前版本。然后选择要复制到新 API 的元素。

    复制元素会在您的工作区中创建一个新副本。新元素将在其名称后附加新版本号，例如my-docs-2.0.0. 新元素将链接到新版本的 API。

  5. 选择创建版本。您的新版本将在 API Builder 中打开。

重命名和删除版本

您可以使用左侧边栏中的查看更多操作( ) 菜单重命名、编辑或删除 API 版本。三个点图标编辑 API 可让您立即更改名称、状态和可见性。

当您删除 API 版本时，与其关联的集合、监视器、模拟和环境不会被删除或移除。

使用 API 版本

发布是对 API版本的定期增量更改。您定期创建一个版本来发布对 API 所做的更改。版本可以具有语义版本名称 ( 3.2.0-beta) 或动态命名 ( 2021-12-25, Q4 Security Update)。

当您连接到外部 Git 存储库时，可以将发布映射到 Git 发布标签。

查看版本

版本显示在API 版本页面的概览选项卡上。将鼠标悬停在版本上并选择查看版本以打开该版本的页面。

API 生成器版本

每个发布页面都显示与该发布相关的架构、文档和测试的只读视图。您不能对已发布的 API 进行更改；如果您有更多更改，您可以创建另一个版本。

创建发布

要创建发布：

  1. 如果您使用的是外部 Git 存储库，请首先在 Git 中通过将更改从开发分支合并到主分支并创建发布标签来创建发布。
  2. 选择侧栏中的更改日志图标 ( 更改日志图标)。Changelog 将显示 API 版本的架构和相关元素的更改。
  3. 选择+ 发布更改。
  4. 输入版本名称和描述。
  5. 如果您使用的是外部 Git 存储库，请在Git release中选择一个标签。
  6. 如果您希望新版本可见，请选择使该版本可供消费者使用。否则，它只对编辑可见。
  7. 选择创建发布。您将被带到发布的新页面。

您还可以在变更日志中编辑版本名称。在版本旁边，选择三个点图标，然后选择编辑。

设置 API 状态

API 状态是一个文本标签，您可以更改它以指示开发周期内 API 版本的当前阶段。例如，您可以选择“设计中”、“安全审查”或“生产中”等状态。您可以为 API 的每个版本设置不同的状态。

状态不会影响 API 的可见性、权限或可用性。它只是一种告诉团队中其他人 API 当前状态的方法。文件中的任何操作或状态更改都不会自动更改状态。您可以随时更改状态。

状态显示在 API 选项卡的左上角。要设置新状态，请从下拉列表中选择一个。