1 Swagger简介

1.1 概要

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。 总体目标是使客户端和文件系统作为服务器以同样的速度来更新。 文件的方法/参数/模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

Swagger 是最流行的 API 开发工具，它遵循 OpenAPI Specification（OpenAPI 规范，也简称 OAS）。

Swagger 可以贯穿于整个 API 生态，如 API 的设计、编写 API 文档、测试和部署。

Swagger 是一种通用的，和编程语言无关的 API 描述规范。

1.2 Swagger序列化

1.3 官方地址

https://swagger.io/

2 Swagger实操

2.1 环境

（1）操作系统：window或者ubuntu

（2）浏览器：谷歌或者火狐

（3）数据库：mysql5.6，外网可以访问的或者部署主机内部可以访问

2.2 准备

（4）创建新的数据库实例：

连接mysql后，执行以下sql

2.3 实操

（5）登录软开云并创建项目

浏览器打开https://www.huaweicloud.com

按照此步骤登录到软件开发服务上，如果没有华为云账号需要先去注册。

登录之后开始创建一个项目

（6）创建代码仓库

进入新建的项目后，依次点击代码→代码托管→新建仓库，创建一个代码仓库

选择模板新建，左侧搜索swagger，选择Web Server，点击搜索后选择右侧swagger-devcloud仓库，输入仓库名称后点击确定，创建完成。

（7）修改配置文件

点击刚刚创建的代码仓库

依次点击上方第三步的路径后，点击application.yml配置文件

点击编辑后，修改数据库的访问地址，修改数据库口令密码，然后在下方填写备注后点击确定。

（8）编译

在当前项目下依次点击构建&发布→编译→新建，创建一个编译任务，填写任务名称后点击下一步

选择Maven模板然后点击确定

确认代码仓库与分支，默认值即可，添加版本执行参数（虽然本文未用到但在学习流水线时会用到），然后点击第三步，Maven构建

依次确认第二，第三步

第二步手动选择：maven3.3.1-jdk1.8

第三步手动填写：mvn package -Dmaven.test.skip=true

确认后点击第四步，上传软件包到发布仓库

第二步填写：**/target/*.?ar

第三步填写：${version}

第四步填写：swagger-devcloud

确认后点击新建→开始构建

构建完成。

（9）添加授信主机（部署机）

将服务器主机授信到DevCloud里，用于部署网站。

点击“设置-通用设置-主机组管理”，将服务器以主机组的形式授信到项目当中。

新建主机组：

在主机组中添加主机：

（10）部署

回到当前项目下，创建模板部署任务

填写任务名称后点击下一步，选择模板：SpringBoot应用部署

点击“确定”后，选择部署步骤。

SpringBoot应用部署模板当中包含以下步骤：

停止SpringBoot服务（如果可能的话）、安装JDK（如果可能的话）、选择部署来源（将软件包传输到主机上）、启动SpringBoot服务

注意每个步骤的路径及主机组信息确保正确。

点击“保存”后，任务创建完毕。

点击“执行”执行部署任务。

3 Swagger应用

3.1 访问方式

Ip:8001/swagger-ui.html

3.2 常用功能

（11）下载swagger测试脚本

第一步：右键另存测试脚本

第二步：单机链接另存为，保存swagger测试脚本到本地

（12）接口测试

依次点击user-controller→GET /user

点击Try it out，下方会展现获取的用户数据

3.3 自动化测试

（13）导入测试脚本

依次点击测试→接口测试→脚本模板→导入swagger文件（三→2→(1)中导出的）

（14）编写接口测试用例

依次点击测试→接口测试→测试用例→新建，输入用例名称后点击保存并编写脚本

先点击准备进入准备阶段，然后将第二步的接口拖入到第三步的位置，然后点击第三步的接口名称

配置请求参数，第二步可默认，第三步需要填写mode信息：

{"address": "测试地址","age": "25","email": "测试邮箱@测试.com","name": "测试者","password": "123456","phone": "15141133332","sex": "男","status": "zc","type": "zc","username": "ceshi"}

然后配置请求头

第二步选择：Access-Control-Request-Headers

第三步填写：{"Accept": "application/json;charset=UTF-8"}

属性填写：${code}

比较选择：==

值填写：200

参数类型选择：String

参数名填写：name

属性填写：${body}.name

点击测试，进入测试阶段，将左侧的queryUserListUsingGET拖到右侧，然后依次点击接口名称→请求参数

第二步可默认

第三步填写：${name}

点击请求头，填写名称，值

名称选择：Access-Control-Request-Headers

值填写：{"Accept": "application/json;charset=UTF-8"}

点击检查点，设置检查值

填写属性：${body}

选择比较：contains

填写值：${name}

点击传递变量，为下一阶段传递参数

参数类型选择：String

参数名填写：user_id

属性填写：${body}[0].id

点击销毁阶段，销毁测试数据，将左侧的deleteUserUsingDELETE拖拽到右侧，然后依次点击接口名称→请求参数

步骤三可默认

步骤四填写：${user_id}

点击请求头，设置请求头数据

名称选择：Access-Control-Request-Headers

值填写：{"Accept": "application/json;charset=UTF-8"}

点击检查点，设置检查值

属性填写：${body}

比较选择：be true

传递参数默认不填，点击右上角调试按钮，开始调试脚本

右侧显示调试日志，滚动到最下方，每个检查点显示通过即表示测试通过

回到接口测试用例管理页面后，可通过点击运行按钮，来启动测试脚本

（15）自动测试

依次点击测试→接口测试→测试套件→新建测试套件

填写套件名称：用户测试套件

选择责任人

点击保存

点击编辑后，开始编辑测试用例

点击添加用例，将之前做的接口测试放进去，如有需要可以添加多个测试用例

点击执行，当下面测试用例结果展现成功后点击返回按钮，套件制作完成

依次点击编译构建→流水线→新建流水线

填写流水线名称后，给流水线设置为4个阶段，分别为：

开始→ci→cd→test

开始阶段保留一个参数，点击编辑后参照右侧

名称：version

类型：字符类型

默认值：1.0.0

勾选提交代码自动触发流水线后，即可实现自动测试了，当代码版本发生变化后自动出发流水线编译部署测试等环节。

编辑ci阶段，参照右侧

类型选择：构建

选择swagger-devcloud构建任务

版本填写：${version}

第四步选择ci阶段生成的软件包

选择之前制作的测试套件：用户测试套件，然后点击保存

点击全新执行，测试流水线是否配置成功

3.4 代码说明

（16）Maven中加入swagger依赖

（17）编写swagger配置文件

（18）编写rest风格的接口

①定义模块名称

②定义接口名称以及说明

③定义参数类型

④定义接口路径以及调用方式编码等