接口文檔生成流程
介紹
目前我們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。預知後事如何, 請看下集預告。(寫文檔碼字太久要去幹活兒了)