Postman工作协同：生成接口文档和示例，超实用

Postman这个Documentation功能对于前后端分离的团队，接口开发团队来说真的是提升沟通效率和工作效率的一个利器。废话不多说，直接上干货来看如何通过Postman来生成接口文档和发布接口文档，以及如何定制化文档中的内容。

流程概要：

定义一套接口，为接口生成文档和示例一般来说有以下步骤：（这里只列出postman参与的部分）

创建一个接口集合，描述该接口集合的功能、范围等信息

• 将所有需求已清晰的接口定义到集合当中

• 创建接口（add request)，描述该接口的作用

• 为该接口上的所有参数增加描述信息（params, header, body）

• 为接口生成样例

• 成功样例

• 失败样例

• 异常样例

• 重复前两个步骤，完成接口集中的接口定义

• 创建文档

接下来，以elasticsearch 的Restful API 接口作为一个示例，来展示如何用Postman生成接口文档和示例；

创建接口集合

假设，我们要开发elasticsearch的增删改查服务，并且已经在团队内对接口达成了共识，并将为其创建可维护的文档。

创建接口(add request),描述该接口的作用

如上文提到，我们有4个接口,增,删,改,查,可对elasticsearch中的索引进行对应操作。首先，让我们添加一个create文档的接口。并添加对接口对简单描述：

为该接口上的所有参数增加描述信息(params, header, body)

填入接口的细节：

为接口生成样例

成功样例:

在创建样例的时候，我们可以根据约定好的返回内容，填充到样例中（example）。

在接口已经开发好的情况下，我们还可以点击send按钮，直接将接口的response保存为样例：

我们还可以创建一个稍微复杂的样例，比如列出接口上可用的参数：

失败样例:

同样，我们可以保存一个失败的样例，比如，当date类型的值，被输入一个字符串的时候，接口将会报错。

异常样例:

我们可以类比之前的两个样例，依葫芦画瓢，这里就不再重复。

创建并查看文档

在将接口都创建到集合之后，我们就可以创建文档了，具体的方法很简单，在集合的选项中，点击view in web，即可看到创建的文档，以及文档中的示例：

发布文档

在接口经过数轮的修改，可以发布之后，我们也可以发布接口文档了。这里，postman团队背靠google是很有钱的，它提供了域名和服务器为我们存储在互联网上发布所有人都可以查看的文档：

根据接口示例创建mock服务

这个mock server仍然是postman团队为我们提供的域名和服务器，因为我们在创建接口文档的过程中，已经创建了各种样例，所以，我们是可以直接生成mock server，而不需要额外的工作的。

最后感谢每一个认真阅读我文章的人，礼尚往来总是要有的，这些资料，对于【软件测试】的朋友来说应该是最全面最完整的备战仓库，虽然不是什么很值钱的东西，如果你用得到的话可以直接拿走：

这些资料，对于【软件测试】的朋友来说应该是最全面最完整的备战仓库，这个仓库也陪伴上万个测试工程师们走过最艰难的路程，希望也能帮助到你！