接口文档生成流程

介绍

目前我们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")

这里就是字段的约束。