邻居的尾巴个人页面-阿里云开发者社区

我有接口文档, 你有酒吗？

接口文档生成流程介绍目前我们QA在测试过程中, 存在着接口文档不全或有出入(包括更新)的情况。这时候我们一般会阅读开发编写的代码或者直截了当去问开发。这2种方法的弊端都很明显, 即增加了沟通和时间成本。自己看代码且不论QA对于开发语言的熟悉程度, 有的代码QA并不可见。独自研究费时费力, 去找开发询问的时候，得问到对应的人, 他们还需要花费时间精力去搜寻。 ==现在, 这些问题都将迎刃而解==。原理介绍通过swagger插件(如jar包)解析编写了接口注解的java代码, 而后通过生成的swagger.json文件解析出接口信息并导入接口文档管理工具(yapi)。第一步: 编写注解 swagger是一个较为流行的接口文档管理工具, 但是这里我们不打算将他作为我们的大方向。其实接口文档的核心基本都已固定, 如path(route), 参数, 响应, 请求方式等。swagger在这点做得相当不错, 使用json-schema约束json字段的属性(required, example, type等)。简而言之, 第一步就是通过注解对java中各个字段的参数做了约束, 通过插件生成json文档。下面我们来看一个例子: example地址, 这是一个长得像外国人的中国老哥我们来看下注解的具体实现 package com.github.kongchen.swagger.sample.wordnik.resource; import com.fasterxml.jackson.annotation.JsonProperty; import io.swagger.annotations.*; import com.github.kongchen.swagger.sample.wordnik.model.LoginData; import javax.ws.rs.FormParam; import javax.ws.rs.POST; import javax.ws.rs.Path; import javax.ws.rs.Produces; import javax.ws.rs.core.Response; @Path("/login") @Api(value = "login", description = "登录接口") @Produces({"application/json"}) public class woodyTest { @POST @ApiOperation(value = "用户登录") @ApiResponses(value = {@ApiResponse(code = 400, message = "Invalid ID supplied"), @ApiResponse(code = 404, message = "Order not found")}) public Response getSuite( @ApiParam(value = "登录请求json参数", required = true) LoginData data) { System.out.println(data); return Response.ok().entity("").build(); } } ==图中的@POST, @ApiResponses, @Path等@== 意味都比较显著了吧, 因为我的java只有一点点语法基础, 所以理解可能有点出入, 我这里简单理解为注释的意思。如有不对求指教=。= 接下来我们来看看LoginData怎么写。 package com.github.kongchen.swagger.sample.wordnik.model; import io.swagger.annotations.ApiModelProperty; import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; import java.util.Date; @XmlRootElement(name = "LoginData") // 这是xml的信息, 我这里都去掉了不用 public class LoginData { @ApiModelProperty(value="用户名", name="user", example = "wuranxu") private String user; @ApiModelProperty(value="用户密码", name="pwd", example = "wodemimajiushimeiyoumima", required = true) private String pwd; @XmlElement(name = "user") public String getUser() { return user; } public void setUser(String user) { this.user = user; } @XmlElement(name = "pwd") public String getPwd() { return pwd; } public void setPwd(String pwd) { this.pwd = pwd; } } 这个类里面, 有user和login属性, 分别给属性加了类似这样的注解 @ApiModelProperty(value="用户名", name="user", example = "wuranxu") 这里就是字段的约束。第二步: 通过注解生成swagger.json 下载第一步那个小哥给出的demo, 解决好pom文件的依赖后。在demo目录执行: mvn clean compile 可以看到图中目录生成了swagger.json 来看看生成的json 第三步: 导入yapi 先来介绍下yapi吧~ yapi是去哪儿的大前端团队开发，基于react+antd的一套接口文档管理工具。给个掌声, 真的很良心。具体地址大家可以试用了感受一下。至于不需要yapi, 钟爱原生swagger的童鞋, 也可以直接将swagger.json放入你的本地swaggerUI中查看接口文档啦。那么附上一张swagger的截图吧... 后话其实缺点就是开发需要在每个model的类加上注解, 写每一个接口也需要注解, 开发不好惹千万千万不要推:) 当然还有第四步啦, 因为···这些都是手动干的啊, 没人有那么多精力去手动维护这些破json。预知后事如何, 请看下集预告。(写文档码字太久要去干活儿了)

邻居的尾巴个人页面-阿里云开发者社区

个人介绍

擅长的技术

我有接口文档, 你有酒吗？

面试被虐记

Centos安装Python3(自带pip和setuptools)

分享一个Appium/selenium测试报告模板

个人觉得实用的Python姿势

Selenium里可以自行封装与get_attribute对应的set_attribute方法

关于xlrd处理合并单元格

Flask下载文件

使用flask_sqlalchemy

Pymongo一些常见需求(陆续补充)

Android虚拟机安装

个人觉得实用的Python姿势

分享一个Appium/selenium测试报告模板

Centos安装Python3(自带pip和setuptools)

面试被虐记

我有接口文档, 你有酒吗？