接口文檔生成流程

介紹

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

這里就是字段的約束。