泽民博客 ☰ Menu

Swagger与postman使用

Swagger接口文档，在线自动生成模板和页面。服务器地址加上swagger-ui.html后缀即可访问到（https://域名:端口号/swagger-ui.html）。
使用时在java代码中引用navan管理pom.xml中添加依赖：



com.mangofactory
swagger-springmvc
1.0.2



API接口文档标识的内容只用于注释，没有实际意义，表示必须传入，只在文档中提示，没传不提示报错。若想判断，可在参数前些@requestParam注解
写好API注解文档后，启动项目。可以在swagger.html中对接口进行模拟测试，简单方便。



我目前更多的使用Swagger管理API文档，测试接口。管理Bean个人并不常用。可以把Swagger理解为接口文档，后台写好的代码可以直接生成前端接口文档页面，接口调用这可以通过这个页面发送接口请求，进行接口测试或调用。对接方便。无奈的是，返回参数的接口文档，还是要自己写啊。
        Postman插件，postman只是Chrome浏览器一个控件，可以嵌在Chrome中使用，也可以单独下载软件版。用来测试接口非常只方便。而且可以分类管理测试过的接口。



它得好处就是可以记忆测试的参数，Swagger毕竟是网页打开，很多参数无法保存。对家数据测试造成不小困扰，另外。设计到token权限的话，swagger中可能每次都需要模拟登录，而postman在Header中保存Token信息。给测试带来便利



手写Api文档的几个痛点：



文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
接口返回结果不明确
不能直接在线测试接口，通常需要使用工具，比如postman
接口文档太多，不好管理



swagger就是一款让你更好的书写API文档的框架。
什么是swagger2
编写和维护接口文档是每个程序员的职责，根据Swagger2可以快速帮助我们编写最新的API接口文档，再也不用担心开会前仍忙于整理各种资料了，间接提升了团队开发的沟通效率。



常用注解
swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。



@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数



@RequestBody



该注解常用来处理Content-Type: 不是application/x-www-form-urlencoded编码的内容，例如application/json, application/xml等；它是通过使用HandlerAdapter 配置的HttpMessageConverters来解析post data body，然后绑定到相应的bean上的。



restful风格接口
URL定位资源，用HTTP动词（GET,POST,DELETE,DETC）描述操作。



识别(identify)、 表示(represent) 、交互(interact with)。



看Url就知道要什么
看http method就知道干什么
看http status code就知道结果如何





  1. REST描述的是在网络中client和server的一种交互形式；REST本身不实用，实用的是如何设计 RESTful API（REST风格的网络接口）；




  2. Server提供的RESTful API中，URL中只使用名词来指定资源，原则上不使用动词。“资源”是REST架构或者说整个网络处理的核心。比如：





http://api.qc.com/v1/newsfeed: 获取某人的新鲜;



http://api.qc.com/v1/friends: 获取某人的好友列表;



http://api.qc.com/v1/profile: 获取某人的详细信息;




  1. 用HTTP协议里的动词来实现资源的添加，修改，删除等操作。即通过HTTP动词来实现资源的状态扭转：



GET 用来获取资源，



POST 用来新建资源（也可以用于更新资源），



PUT 用来更新资源，



DELETE 用来删除资源。比如：



DELETE http://api.qc.com/v1/friends: 删除某人的好友 （在http parameter指定好友id）



POST http://api.qc.com/v1/friends: 添加好友



UPDATE http://api.qc.com/v1/profile: 更新个人资料





  1. Server和Client之间传递某资源的一个表现形式，比如用JSON，XML传输文本，或者用JPG，WebP传输图片等。当然还可以压缩HTTP传输时的数据（on-wire data compression）。




  2. 用 HTTP Status Code传递Server的状态信息。比如最常用的 200 表示成功，500 表示Server内部错误等。





1、REST 是面向资源的，这个概念非常重要，而资源是通过 URI 进行暴露。



比如：左边是错误的设计，而右边是正确的



GET /rest/api/getDogs –> GET /rest/api/dogs 获取所有小狗狗
GET /rest/api/addDogs –> POST /rest/api/dogs 添加一个小狗狗
GET /rest/api/editDogs/:dog_id –> PUT /rest/api/dogs/:dog_id 修改一个小狗狗
GET /rest/api/deleteDogs/:dog_id –> DELETE /rest/api/dogs/:dog_id 删除一个小狗狗



2、REST很好地利用了HTTP本身就有的一些特征，如HTTP动词、HTTP状态码、HTTP报头等等。



HTTP动词
GET 获取一个资源
POST 添加一个资源
PUT 修改一个资源
DELETE 删除一个资源
HTTP状态码
200 OK
400 Bad Request
500 Internal Server Error
HTTP报头
Authorization 认证报头
Cache-Control 缓存报头
Cnotent-Type 消息体类型报头
……



怎么用RESTful
1、每个资源使用2个URL，网址中只能有名词



2、对于资源的操作类型由HTTP动词来表示



3、统一的返回结果



4、返回正确的状态码



5、允许通过HTTP内容协商，建议格式预定义为JSON



6、对可选发杂的参数，使用查询字符串（？）



7、返回有用的错误信息(message)



8、非资源请求用动词，这看起似乎和1中的说法有矛盾，但这里指的是非资源，而不是资源



postman简介
Postman 是一个很强大的 API调试、Http请求的工具，当你还准备拿着记事本傻傻的去写 Form 表单的时候，你来试试 Postman。



Postman 提供功能强大的 Web API 和 HTTP 请求的调试，它能够发送任何类型的HTTP 请求 (GET, POST, PUT, DELETE…)，并且能附带任何数量的参数和 Headers。不仅如此，它还提供测试数据和环境配置数据的导入导出，付费的 Post Cloud 用户还能够创建自己的 Team Library 用来团队协作式的测试，并能够将自己的测试收藏夹和用例数据分享给团队。



postman安装
1、app下载地址



https://app.getpostman.com/app/download/win64
2、谷歌插件方式



postman常用按钮
导入：用于导入你或团队保存的API请求文件，json格式。
新建文件夹：用于API请求分门别类，便于管理。
保存请求：保存你的API请求，返回值也能存储下来。
下载：下载你测试通过的API请求，团队共享，导入。json格式，可手动编辑的。
Postman 是有团队协作的，可以共享请求参数及数据，但需要注册且是放在他们的服务器上的，对公司而言，会有安全性的考虑，大多数人很懒，会放弃这种方式。还是 QQ 发送文件来的方便。



postman使用流程
新建项目



直接点击左边上面的添加目录图标来新增一个根目录，相当于新建了一个项目，我们可以把一个项目或一个模块的用例都存放在这个目录之下，并且在根目录之下我们还可以在建立子目录来进行功能用例的细分，



新建用例



点击右侧区域的+号，新增一个空用例的模板，也可以通过复制一个已有用例来达到新建一个用例的目的，2种方法



添加请求信息



新建的用例请求为空，需要添加请求信息，如下图所示：



1）选择一个请求方法，如：get或post



2）填写请求的url，如：http://www.baidu.com



3）如果是get则请求参数直接写在url后，用？连接



4）如果是post则请求添加在body中



5）点击“send”发送请求



6）查看请求响应内容



Post请求参数示例：



post请求的主要特点是把请求数据放在body中，而非url后



全局变量与环境变量



全局变量我们可以自己在预处理和结果处理2个脚本环境里进行赋值



在具体的测试数据里我们就可以直接使用，具体的使用方法是为：；比如你在脚本中可以设置全局变量：



postman.setGlobalVariable(“username”, “tester”);



那么在用例数据项里面我就可以这样使用，，用来代表具体的tester值



而环境变量的设置与使用与全局变量基本一样，只是环境变量我们还有另外一个入口可以进行设置，那就是环境配置管理中，



我们可以预先建立若干和与环境相关的一套变量，根据实际的测试需求在执行前选择对应的环境变量模板，



这样可以快速切换测试服务器与线上服务器之前的环境差异。



比如：配置2套环境变量模板，一套url是测试环境，另一套为线上环境，根据测试对象不同我们选择不同的环境变量模板就行了，而不再需要修改测试数据中的url了，如下图所示：



上面我们就把请求的host提取出来，然后在不同环境变量模板里使用不同的url值，后面我们就可以通过选择不同的环境变量模板来进行对应的请求测试



导出用例为代码



postman还有一个很赞的地方就是导出用例为CODE，即如果你编写好了用例之后可以通过点击“Generate Code”来一键生成代码，并且还有好多语言和类库可以选择



批量执行用例



这个功能由单独的runner来负责的，我们需要在另外的界面进行操作



依次点击上面的按钮就会出现runer界面，如下直接点击“Start run”即可，



#swagger api一键导入postman
在用postman进行接口测试时，对于参数较多的接口时第一次添加接口参数是比较繁琐的，可利用swagger一键导入api接口，事例如下：
1、获取swagger地址
2、打开postman，点击import，贴入swagger的url即可


Category golang