Postman进阶功能-集合分支管理与编写接口文档

        大家好，在接口测试的领域中，我们不断追求更高效、更便捷、更强大的方法与工具。而 Postman 作为一款备受青睐的接口测试工具，其进阶功能更是为我们打开了新的天地。在这其中，集合分支管理与编写接口文档的功能显得尤为重要。

        当面对日益复杂的接口体系和项目需求时，集合分支管理能够让我们有条不紊地组织和分类接口，使得测试工作更加清晰有序。它就像是为我们的接口测试之旅提供了清晰的导航，帮助我们在众多接口中准确找到目标。

        而编写接口文档这一功能，更是意义非凡。它让接口信息不再孤立，而是形成一个有机的整体。无论是团队协作还是项目交接，详细准确的接口文档都是关键的支撑。它确保了知识的传递和延续，避免了因信息缺失而导致的误解和错误。

一、集合的分支管理

        像 Git 一样，在 Postman 中也有源码管理功能，通过创建团队的 workspace，团队成员就可以在这个 workspace 中像 Git 管理源代码一样，去创建分支、合并分支、拉取分支等。接下来，来了解下 Postman 的这几个功能。

• 创建集合分支（Create a fork）
• 合并变更（Merge changes）
• 创建 pull 请求（Create Pull Request）

1、创建集合分支

        分支的创建，需要基于某个集合中的集合分支创建后，如此，相当于这个集合的主分支，团队成员可以基于这个分支拉取一个新的分支开发，最后，将修改后的新的脚本合并到主分支上。

接下来是创建一个分支：

（1）选中一个集合，点击(...)或右键，点击“Create a fork”。
（2）在弹出的对话框中输入 Fork Label，选择团队的 workspace，点击“Fork collection”。
（3）进入到对应的 workspace，就会查看到对应的 Collection，这里的每个集合，其后都有一个 fork 标志。

2、合并变更

        当在集合中加了新的功能后，就需要把这些变更提交到主分支上，提交成功后，团队成员也就能看到最新的修改数据了。具体操作如下：

（1）点击 Collection 右侧的（...），点击 Merge Changes。
（2）在弹出的页面中，点击右上角的 Merge all changes。注意，此时如果 Merge，Postman 则会提示已经有最新更新了，会提示你去 Pull Changes，这时，你可以先拉取最新的变更，然后再点击 Merge all changes。
（3）在弹出的新对话框中，默认选择 Merge changes，点击 Merge。

3、创建 Pull 请求

当团队提交了最新修改后，就可以通过 Create Pull Request 拉取最新的修改数据。

具体步骤如下：

（1）点击 Collection 右侧的（...），点击 Create pull Request。

（2）在弹出的页面中，输入 title 和描述，点击 Create pull Request。

（3）查看 Postman 请求，最新的更新就会拉取到本地的分支集合中。

 

        在使用的过程中，Postman 中的 Create a fork、Create pull request、Merge change 特别像Git 中的 create branch、pull、push。

二、编写接口文档

        在进行接口测试之时，常常会遭遇所填写的请求数据不清晰这类问题，而这时首先会想到的便是接口文档。然而，在许多情况下，开发人员所撰写的文档并不够完善，其更新也并不够及时，甚至就算更新了，大家也需要跳出工具去寻找对应的接口文档，这给用户带来的体验相当不好。所以，当下出现的一些工具，既能够支持接口调试，同时也支持文档查看，无需在工具与文档之间反复来回地切换。Postman 也同样如此，在 Postman 当中，同样是支持编写接口文档的，并且它的文档功能还极为强大。

1、生成文档

生成文档有两种方式，直接打开链接和新建 API 文档。

第一种：直接打开链接非常简单，首先，选择一个集合，然后，点击右三角 -> 点击 View in web。

第二种，操作步骤如下：

（1）点击左上角的 New，选择 API Documentation 。
（2）弹出的第一个 Tab 页面，有两个选项，新建一个集合/从已有集合选择。这里，根据自己的实际需求来选择即可。
（3）进入到第二个 Tab 页面，输入对集合的一些基本描述，比如基本介绍、认证方式、错误码等。
（4）进入到第三个 Tab 页面，这时会弹出一个链接，直接点击链接，就会进入到接口文档页面。如下图所示：

        以上两种方式，都可以进入文档链接，主要区别在于第二种可以加入一些整体性的说明，如系统概况、认证方式、错误码等。另外，文档是以 Web 形式展现，所以相关查阅者只要知道这个链接，就都可以通过浏览器进行访问。

2、编写文档

        编写文档同样有两种方式，分别是在本地编辑和打开链接在浏览器中进行编辑。无论哪种编辑方式，保存成功后都会自动同步。

本地编辑步骤：

（1）点击集合的右三角，会自动弹出 RUN 的窗口。
（2）选择一个请求点击后，会出现两个链接按钮，分别是 Add a description 和 Open in builder。
（3）点击 Add a description，填写接口描述即可。

在线编辑步骤：

（1）点击集合的右三角，会自动弹出 RUN 的窗口。
（2）点击 View in web，会在浏览器中自动打开该集合的 Web 链接地址。
（3）选择其中请求，点击 Add a description。 

        以上两种方式都可以给接口添加文档描述，且都支持 markdown 语法，编写好的信息也能及时的在文档中所看到，如下图所示是给某个接口添加的文档信息。

点击 Open in builder 这个链接按钮，也能直接打开对应的请求。

以下是以 Web 方式打开的在线文档，在线文档还有个比较实用的功能，就是为每个请求自动生成不同语言的代码，如果你刚好对如何用代码实现不太清楚，可以直接从这里拷贝。