0


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. 不添加协作人,也可以分享接口文档链接

在这里插入图片描述

6. 接口文档的导入与导出

Postman如何导出接口的几种方法


本文转载自: https://blog.csdn.net/weixin_40022980/article/details/125538227
版权归原作者 小男孩tom 所有, 如有侵权,请联系我们删除。

“Postman写接口文档”的评论:

还没有评论