我有接口文档, 你有酒吗?
接口文档生成流程
介绍
目前我们QA在测试过程中, 存在着接口文档不全或有出入(包括更新)的情况。
这时候我们一般会阅读开发编写的代码或者直截了当去问开发。
这2种方法的弊端都很明显, 即增加了沟通和时间成本。
自己看代码且不论QA对于开发语言的熟悉程度, 有的代码QA并不可见。独自研究费时费力, 去找开发询问的时候,得问到对应的人, 他们还需要花费时间精力去搜寻。
==现在, 这些问题都将迎刃而解==。
原理介绍
通过swagger插件(如jar包)解析编写了接口注解的java代码, 而后通过生成的swagger.json文件解析出接口信息并导入接口文档管理工具(yapi)。
第一步: 编写注解
swagger是一个较为流行的接口文档管理工具, 但是这里我们不打算将他作为我们的大方向。其实接口文档的核心基本都已固定, 如path(route), 参数, 响应, 请求方式等。swagger在这点做得相当不错, 使用json-schema约束json字段的属性(required, example, type等)。
简而言之, 第一步就是通过注解对java中各个字段的参数做了约束, 通过插件生成json文档。
下面我们来看一个例子:
我们来看下注解的具体实现
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。预知后事如何, 请看下集预告。(写文档码字太久要去干活儿了)
低调大师中文资讯倾力打造互联网数据资讯、行业资源、电子商务、移动互联网、网络营销平台。
持续更新报道IT业界、互联网、市场资讯、驱动更新,是最及时权威的产业资讯及硬件资讯报道平台。
转载内容版权归作者及来源网站所有,本站原创内容转载请注明来源。
- 上一篇
Java并发编程笔记之基础总结(一)
一.线程概念 说到线程就必须要提一下进程,因为线程是进程中的一个实体,线程本身是不会独立存在的。进程是代码在数据集合上的一次运行活动,是系统进行资源分配和调度的基本单位,线程则是进程的一个执行路径,一个进程至少有一个线程,进程中的多个线程是共享进程的资源的。操作系统在分配资源时候是把资源分配给进程的,但是 CPU 资源就比较特殊,它是分派到线程的,因为真正要占用 CPU 运行的是线程,所以也说线程是 CPU 分配的基本单位。 Java 中当我们启动 main 函数时候其实就启动了一个 JVM 的进程,而 main 函数所在线程就是这个进程中的一个线程,也叫做主线程。 如上图一个进程中有多个线程,多个线程共享进程的堆和方法区资源,但是每个线程有自己的程序计数器,栈区域。、 其中程序计数器是一块内存区域,用来记录线程当前要执行的指令地址,那么程序计数器为何要设计为线程私有的呢? 前面说了线程是占用 CPU 执行的基本单位,而 CPU 一般是使用时间片轮转方式让线程轮询占用的,所以当前线程 CPU 时间片用完后,要让出 CPU,等下次轮到自己时候在执行。 那么如何知道之前程序执行到哪里了?...
- 下一篇
二分法优化
1,基本的二分思想: int BinarySearch(int a[],int size,int key) { int L = 0; //查找区间的左端点 int R = size - 1; //查找区间的右端点 while( L <= R) { //如果查找区间不为空就继续查找 int mid = L+(R-L)/2; //取查找区间正中元素的下标 if( key == a[mid] ) return mid; else if( key > a[mid]) L = mid + 1; //设置新的查找区间的左端点 else R = mid - 1; //设置新的查找区间的右端点 } return -1; } 其实:L+(R-L)/2=(R+L)/2 为了防止(L+R)溢出,才这样写(出于ACM的需要) 2,将L R的初始化边界扩展1 int internalFor(int a[], int l, int r, int key) {//二分法查找a[] l到r区间的某个值 int L = l - 1; int R = r + 1; int mid; while (R - L ...
相关文章
文章评论
共有0条评论来说两句吧...
文章二维码
点击排行
推荐阅读
最新文章
- CentOS8编译安装MySQL8.0.19
- CentOS8,CentOS7,CentOS6编译安装Redis5.0.7
- SpringBoot2整合MyBatis,连接MySql数据库做增删改查操作
- SpringBoot2整合Redis,开启缓存,提高访问速度
- SpringBoot2配置默认Tomcat设置,开启更多高级功能
- Hadoop3单机部署,实现最简伪集群
- CentOS7,CentOS8安装Elasticsearch6.8.6
- CentOS6,7,8上安装Nginx,支持https2.0的开启
- Docker使用Oracle官方镜像安装(12C,18C,19C)
- SpringBoot2编写第一个Controller,响应你的http请求并返回结果