您现在的位置是:网站首页> 内容页

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

  • 大奖游戏手机客户端
  • 2019-04-03
  • 225人已阅读
简介接口文档生成流程介绍目前我们QA在测试过程中存在着接口文档不全或有出入(包括更新)的情况。这时候我们一般会阅读开发编写的代码或者直截了当去问开发。这2种方法的弊端都很明显即增加了沟

接口文档生成流程

介绍

目前我们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.resourceimport com.fasterxml.jackson.annotation.JsonPropertyimport io.swagger.annotations.*import com.github.kongchen.swagger.sample.wordnik.model.LoginDataimport javax.ws.rs.FormParamimport javax.ws.rs.POSTimport javax.ws.rs.Pathimport javax.ws.rs.Producesimport 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.modelimport io.swagger.annotations.ApiModelPropertyimport javax.xml.bind.annotation.XmlElementimport javax.xml.bind.annotation.XmlRootElementimport 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。预知后事如何 请看下集预告。(写文档码字太久要去干活儿了)

1 0 9)

文章评论

Top