Postman写接口文档

参考

如何用Postman写接口文档，团队协作开发

最近为了减少对代码的侵入性，舍弃了之前一直使用的Swagger，但是showdoc写文档又比较麻烦，测试接口也不方便，于是看了一下网上的多篇关于postman写接口文档的文章，并且亲身实验后将经验结合起来在这里做个总结。

首先了解什么是postman

Postman是一个接口测试工具,在做接口测试的时候,Postman相当于一个客户端,它可以模拟用户发起的各类HTTP请求,将请求数据发送至服务端,获取对应的响应结果, 从而验证响应中的结果数据是否和预期值相匹配;并确保开发人员能够及时处理接口中的bug,进而保证产品上线之后的稳定性和安全性。

Postman提供了独立的安装包： https://www.postman.com/downloads/

那么后端如何用postman编写接口文档，并且让前端或者其他开发人员也一起同步协作呢？

4个步骤如下:

1. 注册登录postman

如果你还没有postman的账号，你需要进行注册一个：邮箱、用户名、密码；
如果已经有了账号，那么直接登录即可。

2. 创建项目工作区

登录成功后选择工作区， 默认会有两个工作区，团队式和个人式的工作区会有些许区别。 但是我们可以为某个项目创建一个新的工作区，单独为某个项目的交互服务：

3. 编写接口文档

2.1 创建了项目工作区后，则可以在这个工作区里创建一个或者多个collections且分别命名。这里的collections其实相当于对应项目的各个端：比如api端、admin端（或者可以直接当成一个功能模块）

2.2 然后在对应的collections端右键选择 “add folder” 添加文件夹（这里的文件夹相当于一个功能模块，可以看成是一个controller，比如“产品管理”， 但并不是必须的步骤。主要看个人的编码习惯，如果不分功能模块就不用建文件夹。 项目功能模块比较多需要细分，那么一个文件夹可以当作是一个模块）

2.3 接下来在功能文件夹下可以选择new Request添加请求， 进行接口url的描写：

这样就是一个接口的请求文档了，那么返回值的文档又如何描述呢？看图：

需要点击“Save Response” 选择其中的 “Save as example”, 这时候会生成一个e.g。 然后点击进入e.g，给对应的返回值添加**//注释**就可以了，记得点击保存。

这样就是一个完整清晰的接口文档了。

4. 添加协作人（这一步也可以在创建工作区之初就操作）

这一步主要是让前端或者开发人员之间共享查看该项目的接口文档

这里要注意一下：
1、首先必须在正确的项目工作区进行邀请，不然即使添加成功，对方也看不见分享的内容。
2、添加的对象必须是postman的注册账号，否则添加失败。

5. 不添加协作人，也可以分享接口文档链接