（转）Swagger2 & Postman工具使用

（二期）7、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内部错误等。

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

新建用例

点击右侧区域的+号，新增一个空用例的模板，也可以通过复制一个已有用例来达到新建一个用例的目的，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”即可，

如下图所示：