Postman高级应用(10):给!你要的接口文档——发布文档

版权声明:本文为@李奕锋 原创文章,如需转载,请注明出处! https://blog.csdn.net/qq598535550/article/details/87909251

场景

开发一个项目需要前端和后端的配合,而接口文档则是连接前后端的一个桥梁。接口文档一般由后端驱动完成,当然也可以由前端驱动完成。只要文档一出来,两边都可以同时开干,提高开发效率。你是不是还在烦恼要用什么云文档平台来编写接口说明,完全不需要,因为Postman已经为我们提供了在线文档发布功能。下面,我将告诉大家如何在Postman上预览并发布文档。

在此之前,你最好创建一个Postman帐号并登录,因为之后的章节所介绍的功能都可能要先登录。

实战

  1. 首先创建一个集合(collection),因为集合是文档生成的最小单位。如有需要,可以加上描述,介绍一下这个集合是对应哪一个工程/业务。

  2. 在该集合里创建一个请求(request),我们继续复用之前用过的简单GET请求。添加一些必要的注释,例如params、headers、body等。

  3. 为该请求添加示例(example)。示例其实很好理解,一般好的接口文档都有成功请求的示例,以及失败时的示例,大家主要关注请求的返回值(response)。一对请求值和返回值合起来才能算一个示例。点击Examples(0)Add Example添加示例,我们添加一个请求成功的示例。我们在NAME填入成功作为示例名称,在Status填入成功时返回的HTTP状态码,一般为200 OK,并在返回值RESPONSE中填入成功时返回的数据

  4. 如果接口已经开发完,则不需要造一个返回结果。我们可以点一下Send发送请求得到真实的返回值,点一下返回值附近的Save按钮,把当前的请求值和返回值作为一个示例保存下来,填入示例名字即可。

  5. 重复第2和第3步,把所有请求及对应示例和注释都写好,就可以在线预览文档。点击集合右边的三角形,再点View in web,在web中打开该集合。在页面中,我们可以很直观的看到我们最终发布的文档的样子,左边是文件夹和接口列表,中间顶部是集合介绍,下面是每个接口的请求地址、方法、参数和描述等,最右边是对应的示例。

  6. 当然,现在别人是看不到的,因为你还没发布出去。我们可以点页面右上角的Publish按钮来发布该文档,也可以直接在Postman桌面客户端的集合右键选择Publish Docs发布。在发布设置页面中,记住请勿勾选Collection discover,不然你的文档就会暴露在Postman社区上,你懂的。发布之后就会得到一个地址,可以分享给与你协同的其他开发者,不需要密码访问(当然也设置不了密码)。已发布的文档可以随时修改保存或下架的。

  7. 其他人打开之后可以通过页面右上角的Run in Postman把所有请求一键导入到自己的Postman桌面客户端(前提是你电脑已经安装最新版Postman,貌似chrome插件版享受不到这项功能)。

更多内容请阅读《Postman高级应用》专栏

展开阅读全文

没有更多推荐了,返回首页