（转）Swagger2 & Postman工具使用

（二期）七、swagger2与postman

 

【课程七】swagge...tman.xmind0.3MB

【课程七预习】sw...tman.xmind31.3KB

 

随着互联网技术的发展，如今的网站架构基本都由原来的后端渲染变成了：前端渲染、前后端分离的形态，而前端和后端的惟一联系，变成了API接口；API文档变成了先后端开发人员联系的纽带，变得愈来愈重要。包括app开发人员和后端直接的交流都是基于api文档。

手写接口文档

手写Api文档的几个痛点：

1. 文档须要更新的时候，须要再次发送一份给前端，也就是文档更新交流不及时。

1. 接口返回结果不明确

1. 不能直接在线测试接口，一般须要使用工具，好比postman

1. 接口文档太多，很差管理

 

• swagger就是一款让你更好的书写API文档的框架。

什么是swagger2

编写和维护接口文档是每一个程序员的职责，根据Swagger2能够快速帮助咱们编写最新的API接口文档，不再用担忧开会前仍忙于整理各类资料了，间接提高了团队开发的沟通效率。

经常使用注解

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

• @Api：修饰整个类，描述Controller的做用

• @ApiOperation：描述一个类的一个方法，或者说一个接口

• @ApiParam：单个参数描述

• @ApiModel：用对象来接收参数

• @ApiProperty：用对象接收参数时，描述对象的一个字段

• @ApiResponse：HTTP响应其中1个描述

• @ApiResponses：HTTP响应总体描述

• @ApiIgnore：使用该注解忽略这个API

• @ApiError ：发生错误返回的信息

• @ApiImplicitParam：一个请求参数

• @ApiImplicitParams：多个请求参数

@Api：用在请求的类上，表示对类的说明

    tags="说明该类的做用，能够在UI界面上看到的注解"

    value="该参数没什么意义，在UI界面上也看到，因此不须要配置"

@ApiOperation：用在请求的方法上，说明方法的用途、做用

    value="说明方法的用途、做用"

    notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明

    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

        name：参数名

        value：参数的汉字说明、解释

        required：参数是否必须传

        paramType：参数放在哪一个地方

            · header --> 请求参数的获取：@RequestHeader

            · query --> 请求参数的获取：@RequestParam

            · path（用于restful接口）--> 请求参数的获取：@PathVariable

            · body（不经常使用）

            · form（不经常使用）    

        dataType：参数类型，默认String，其它值dataType="Integer"       

        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应

    @ApiResponse：用在@ApiResponses中，通常用于表达一个错误的响应信息

        code：数字，例如400

        message：信息，例如"请求参数没填好"

        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息

            （这种通常用在post建立的时候，使用@RequestBody这样的场景，

            请求参数没法使用@ApiImplicitParam注解进行描述的时候）

    @ApiModelProperty：用在属性上，描述响应类的属性

springboot整合swagger2

第一步：导入pom

<!-- Swagger -->

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger-ui</artifactId>

    <version>2.8.0</version>

</dependency>

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.8.0</version>

</dependency>

<!-- END Swagger -->

第二步、SwaggerConfig.java中配置接口文档基本信息和启动swagger2支持

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration

@EnableSwagger2

public class SwaggerConfig {

    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

            .apiInfo(apiInfo())

            .select()

            .apis(RequestHandlerSelectors.basePackage("hello"))

            .paths(PathSelectors.any())

            .build();

    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

            .title("Spring Boot中使用Swagger2构建RESTful APIs")

            .description("欢迎来到java思惟导图社区学习")

            .termsOfServiceUrl("http://www.java-mindmap.com/")

            .version("1.0")

            .build();

    }

}

 

@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: 获取某人的详细信息;

 

3. 用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: 更新我的资料

 

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

 

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

 

一、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 删除一个小狗狗 

 

二、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

一、每一个资源使用2个URL，网址中只能有名词

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

三、统一的返回结果

四、返回正确的状态码

五、容许经过HTTP内容协商，建议格式预约义为JSON

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

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

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

 

postman简介

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

 

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

postman安装

一、app下载地址

• https://app.getpostman.com/app/download/win64

二、谷歌插件方式

postman经常使用按钮

• 导入：用于导入你或团队保存的API请求文件，json格式。

• 新建文件夹：用于API请求分门别类，便于管理。

• 保存请求：保存你的API请求，返回值也能存储下来。

• 下载：下载你测试经过的API请求，团队共享，导入。json格式，可手动编辑的。

Postman 是有团队协做的，能够共享请求参数及数据，但须要注册且是放在他们的服务器上的，对公司而言，会有安全性的考虑，大多数人很懒，会放弃这种方式。仍是 QQ 发送文件来的方便。

postman使用流程

新建项目

直接点击左边上面的添加目录图标来新增一个根目录，至关于新建了一个项目，咱们能够把一个项目或一个模块的用例都存放在这个目录之下，而且在根目录之下咱们还能够在创建子目录来进行功能用例的细分，以下图所示：

2

新建用例

点击右侧区域的+号，新增一个空用例的模板，也能够经过复制一个已有用例来达到新建一个用例的目的，2种方法，以下图所示：

3

添加请求信息

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

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

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

3）若是是get则请求参数直接写在url后，用？链接

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

5）点击“send”发送请求

6）查看请求响应内容

4

Post请求参数示例：

post请求的主要特色是把请求数据放在body中，而非url后，以下图所示：

上面的样例是post方式传输普通参数，若是咱们须要发送带文件的请求时，就要改下请求格式了，具体以下图所示：

注意上面标红框的部分都必需要对应上，以下图所示：

添加请求头信息

有时候请求还须要添加特定的头信息，postman一样能够完美的支持，直接点击Headers标签就能够进行请求头的信息设置，以下图所示：

预处理和结果检查

预处理主要是针对一些环境变量的设置，至关于数据初始化，以下图所示：

响应处理就是对响应结果进行分析和验证，好比检查code是否是200，内容是否是等于具体某个值，是否包含特定的值等等，以下图所示：

由于预处理和结果检查都是使用js做为脚本语言，因此还能够进行任意的js能够实现的场景来辅助测试.

全局变量与环境变量

全局变量咱们能够本身在预处理和结果处理2个脚本环境里进行赋值

在具体的测试数据里咱们就能够直接使用，具体的使用方法是为：{{variable_key}}；好比你在脚本中能够设置全局变量：

postman.setGlobalVariable("username", "tester");  

那么在用例数据项里面我就能够这样使用，{{username}}，用来表明具体的tester值，具体以下图所示：

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

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

这样能够快速切换测试服务器与线上服务器以前的环境差别。

好比：配置2套环境变量模板，一套url是测试环境，另外一套为线上环境，根据测试对象不一样咱们选择不一样的环境变量模板就好了，而再也不须要修改测试数据中的url了，以下图所示：

上面咱们就把请求的host提取出来，而后在不一样环境变量模板里使用不一样的url值，后面咱们就能够经过选择不一样的环境变量模板来进行对应的请求测试。

导出用例为代码

postman还有一个很赞的地方就是导出用例为CODE，即若是你编写好了用例以后能够经过点击“Generate Code”来一键生成代码，而且还有好多语言和类库能够选择，以下图所示：

批量执行用例

这个功能由单独的runner来负责的，咱们须要在另外的界面进行操做，具体以下图所示：

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

以下图所示：