# 浅谈如何优雅的对接口进行单元测试及参数校验

一、当前我们所存在困扰和难题

对于后端开发来说，日常接口文档的编写，接口的调试，以及配合qa去做接口测试大约会占据我们日常百分之三十及以上的工作量。我们现如今开发阶段的开发一个接口的工作流程大概是：1.在wiki对应的项目上去编写接口文档，2.接口开发，3.利用postman去做接口调试。因为这三个步骤互相独立没有任何的耦合性，带来的问题有：1.接口文档的参数与接口真正的参数不一致，很多时候可能先定义好了一个接口文档，但是联调过程中，与前端沟通之后，接口中参数可能会有一些改动，这个时候如果没有及时的去更新接口文档，势必会面临着接口文档和接口中的参数不一致问题。短时间内开发者可能当时会记得传参规则，但时间一长，或者有新同事去接手该项目就会面临巨大的挑战。2.在接口里面做大量的参数校验，会让接口看起来异常的冗杂，无疑会让业务逻辑比较复杂的接口雪上加霜。3.用postman接口调试的时候，当接口内参数较少时还可以凑合着去用。但是一旦接口内参数是一个巨大的结构体，配合上一系列的字段类型限制，非空限制，层层嵌套，很容易让人头晕眼花，提测时，还要去跟qa艰难的沟通各个参数的意思以及规则，大大增加了开发成本。基于这三点，我们可以去利用可视化接口参数管理工具去轻松友好的生成接口文档。

二、swagger工具如何优雅的帮助我们去处理这些难题

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。利用Swagger可以轻松的将接口文档，与接口调式结合在一起。当接口参数出现变更时只用重新定义接口文件重新生成接口文档即可轻松的保持接口文档与接口本身参数的一致性。开发时在接口里面只用专注于接口逻辑本身，不用考虑冗杂的参数校验。Swagger 让部署管理和使用功能强大的API从未如此简单。

三、如何去快速的去生成一个swagger+python+tornado的项目

无论是在现有的功能已完善的代码中加入Swagger还是利用Swagger去重新建一个新项目开发成本都是比较低的。

主要的基本步骤分为：1.编写yaml文件 2.用yaml文件生成接口文档及对应的接口文件 3.将生的静态文件加入主流程里 4.在接口文件里做业务逻辑的处理 5.利用生成的html静态文件进行接口单元测试

以现有的元宝项目ingot为例（该项目较小，业务逻辑较简单）

一、yaml文件编写可分为几个部分：

1.header部分主要是定义Swagger的版本号

2.definitions部分主要是定义返回值以及body里面的结构体

3.parameters部分主要定义args里面的参数

4.paths部分是主体部分，会定义整个接口的主要分支

5.tags部分按模块去划分接口

二、根据yaml文件生成static静态文件

1、安装

pip install swagger-py-codegen

2、根据yaml文件生成static文件

swagger_py_codegen -s docs/v1.yml -p src --ui --spec

Command Options:

-s, --swagger-doc               Swagger doc file.  [required]
-f, --force                     Force overwrite.
-p, --package                   Package name / application name.
-t, --template-dir              Path of your custom templates directory.
--spec, --specification         Generate online specification json response.
--ui                            Generate swagger ui.
--validate                      Validate swagger file.
-tlp, --templates               gen flask/tornado/falcon templates, default flask.
--version                       Show current version.
--help                          Show this message and exit.

以元宝ingot项目为例

$ swagger_py_codegen -s docs/v1.yml ingot -p src -tlp=tornado

四、qa如何去利用swagger去做接口测试

在代码跑起来之后访问 http://127.0.0.1:5000/static/swagger-ui/index.html 即可得到一个可视化单元调试接口

可以直接调试。