更詳細的更全面的教程請觀看作者親自錄製的視頻教程，地址：
開源地址：https://github.com/liukaitydn/LKADocument
一、介紹
在前後端分離，分工更加明細化的今天，爲了減少前端和後臺開發人員的溝通成本，能夠讓他們做到並行開發，同時也能保證前端和後端開發人員所看到的接口文檔的一致性，即時性，以此來大大提高工作效率。所以出現了一些非常優秀的接口管理工具，具有代表性的像Swagger，因爲它能夠通過註解或yml和JSON描述文件來自動生成接口文檔。但是我覺得它不管是在配置過程還是正常使用過程都不是特別好用，特別是對對象參數和複雜的參數註釋很不友好，對前端開發人員更不友好。
所以，LKADocument誕生了！首先解釋一下它的名字，LK是我名字”劉凱“的首字母，A代表接口（API），Document當然是指文檔的意思。LKADocument它也是一款能夠全自動生成接口文檔管理的JAVA後臺插件，沒錯！確實和swagger很像，但也有很多不同點，總體來說，要比swagger配置更簡單，使用起來更方便，在參數註釋和UI展示這一塊功能更加強大，任何複雜的請求參數和響應參數都能夠用註解描述出來，同樣也支持接口在線調試，支持rest風格的接口。UI操作界面更符合中國程序員的口味，同時對前端和後端開發人員更加友好，特別是後端開發人員。先來幾張圖片大家感受一下強大的功能：
二、添加LKADocument插件到SpringBoot項目
1.在項目根路徑創建一個lib文件夾，把LKADocument對應的jar複製進去(目前還沒有放到maven中央或鏡像倉庫，故採用本地引入的方式)：
2.在pom.xml添加依賴引入:
<dependency>
<groupId>LKADocument</groupId>
<artifactId>LKADocument</artifactId>
<version>0.0.1-SNAPSHOT</version>
<scope>system</scope>
<systemPath>${project.basedir}/lib/LKADocument-0.0.1-SNAPSHOT.jar</systemPath>
</dependency>
3.在application.yml添加配置:
lkad:
basePackages: com.xb #指定掃描的包路徑，多個包路徑可以","隔開
projectName: lkad測試項目 #項目名稱
description: 基於LKADocument工具自動生成的接口文檔 #項目描述
enabled: true #是否開啓lkad自動生成接口文檔,默認爲true
4.項目啓動類加上@LKADocument註解
package com.xb;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import com.lk.api.annotation.LKADocument;
@SpringBootApplication
@LKADocument
public class LkaDemoApplication {
public static void main(String[] args) {
SpringApplication.run(LkaDemoApplication.class, args);
}
}
5.打開網址 http://127.0.0.1:8088/lkadocb.html，如果配置沒有問題可以看下如下界面：
注意：目前用火狐和谷歌瀏覽器能正常打開，IE瀏覽器打開顯示有問題
三、快速入門：
1.@LKAType註解：
說明：該註解在類上面使用，爲了兼容Swagger也可以用@Api註解替代
作用：用來標識需要LKADocument掃描的類，該類通常包含需要自動生成接口文檔的API，例如：常用的Controller類
屬性：
value:類說明（如果用@Api註解，此屬性名爲tags）
description:類描述(不是必須)
案例：
/**
簡版：@LKAType("測試類")
完整版：@LKAType(value="測試類",description="該類用來測試LKADocument")
*/
@LKAType(value="測試類",description="該類用來測試LKADocument")
@RestController
public class TestController {....}
2.@LKAMethod註解：
說明：該註解在方法上面使用，只有該方法所屬類加了@LKAType註解纔會生效，爲了兼容Swagger也可以用@ApiOperation註解替代
作用：用來標識需要LKADocument掃描的方法，被掃描到的方法會自動生成接口文檔
屬性：
value:方法說明
description:方法描述（如果用@ApiOperation註解，此屬性名爲notes）
version:版本號，默認值爲"none"
contentType:contentType類型,默認值爲"application/x-www-form-urlencoded",還可取值爲"application/json"
案例：
/**
簡版：@LKAMethod("hello測試")
完整版：@LKAMethod(value="hello測試",description="測試@LKAMethod方法",version="v1.0",contentType=Lkad.X_WWW_FORM_RULENCODED)
*/
@LKAMethod(value="hello測試",description="測試接口",version="v1.0",contentType="application/x-www-form-urlencoded")
@GetMapping("hello")
public String hello() {
return "hello LKADocument";
}
效果圖：
樹版:
橫版:
3.@LKAParam註解和@LKAParams：
說明：該註解在方法上面使用，只有該方法加了@LKAMethod註解纔會生效，爲了兼容Swagger也可以用@ApiImplicitParam和@ApiImplicitParams註解替代
作用：用來描述接口的入參字段
屬性：
value:字段說明
name:字段名稱
description:字段描述
dataType:字段類型,默認值爲String
required:是否必須，取值true或false,默認值爲true
paramType:入參方式，取值query(params入參),header(請求頭入參),path(請求地址入參),默認值爲query
testData:測試數據
isArray:是否是數組入參，取值true或false，默認爲false
type:對象入參，取值對象類型，如果入參是對象，上面除了name屬性必填其它屬性都無效
group:對象屬性分組，配合type屬性使用，取值分組名稱，當入參不需要傳對象所有屬性時可用此屬性分組
案例1：
//params入參
@LKAMethod(value="根據ID獲取用戶信息",version="v1.0")
//簡版:@LKAParam(value="用戶id",name="id")
@LKAParam(value="用戶id",name="id",description="用戶id",dataType="int",required=true,paramType=Lkad.QUERY,testData="1")
@GetMapping("getUser")
public User getUser(Integer id) {
User user = new User();
user.setId(id);
user.setName("小白");
user.setEmail("[email protected]");
user.setAge(22);
return user;
}
//或者path入參
@LKAMethod(value="根據ID獲取用戶信息",version="v1.0")
//簡版:@LKAParam(value="用戶id",name="id")
@LKAParam(value="用戶id",name="id",description="用戶id",dataType="int",required=true,paramType=Lkad.PATH,testData="1")
@GetMapping("getUser/{id}")
public User getUser2(@PathVariable("id")Integer id) {
User user = new User();
user.setId(id);
user.setName("小白");
user.setEmail("[email protected]");
user.setAge(22);
return user;
}
效果圖(只展示樹版)：
案例2：
@LKAMethod(value="新增用戶信息",version="v1.0")
@LKAParams({
@LKAParam(value="登錄token",name="x_token",description="用戶登錄成功後服務器返回的令牌",paramType=Lkad.HEADER,testData="lekwnddfekwes"),
@LKAParam(value="用戶名稱",name="name",description="最多5個漢字",paramType=Lkad.QUERY,testData="小明"),
@LKAParam(value="用戶郵箱",name="email",required=false,paramType=Lkad.QUERY,testData="[email protected]"),
@LKAParam(value="用戶年齡",name="age",description="18-30之間",dataType="int",paramType=Lkad.QUERY,testData="20")
})
@GetMapping("addUser")
public Map<String,Object> addUser(String name,String email,Integer age,@RequestHeader("x_token")String x_token) {
User user = new User();
user.setId(2);
user.setName(name);
user.setEmail(email);
user.setAge(age);
Map<String,Object> map = new HashMap<>();
map.put("code", 200);
map.put("msg", "保存成功");
map.put("result", x_token);
return map;
}
效果圖(只展示樹版)：
4.@LKAModel註解
說明：該註解在對象上面使用，爲了兼容Swagger也可以用@ApiMode註解替代
作用：用來描述model對象
屬性：
value:對象說明
description:對象描述
5.@LKAProperty註解
說明：該註解在對象屬性上面使用，爲了兼容Swagger也可以用@ApiModelProperty註解替代
作用：用來描述model對象的屬性
屬性：
value:屬性說明
description:屬性描述
dataType:字段類型,默認值爲String
required:是否必須，取值true或false,默認值爲true
paramType:入參方式，取值query(params入參),header(請求頭入參),path(請求地址入參),默認值爲query
testData:測試數據
isArray:是否是數組入參，取值true或false，默認爲false
type:嵌套對象入參，取值對象類型，如果入參是對象，上面除了name屬性必填其它屬性都無效
groups:對象屬性分組，多個分組用","隔開
案例：
/*User對象*/
package com.xb.domain;
import com.lk.api.annotation.LKAModel;
import com.lk.api.annotation.LKAProperty;
@LKAModel("用戶對象")
public class User {
@LKAProperty(value="用戶id",testData="3")
private Integer id;
@LKAProperty(value="用戶名稱",groups= {"add"},testData="小紅")
private String name;
@LKAProperty(value="用戶郵箱",groups= {"add"},testData="[email protected]")
private String email;
//groups屬性add後面加-n代表此參數不是必須的，不加-n都是必須的
@LKAProperty(value="用戶年齡",groups= {"add-n"},testData="28")
private Integer age;
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getEmail() {
return email;
}
public void setEmail(String email) {
this.email = email;
}
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
}
/*測試接口*/
@LKAMethod(value="新增用戶信息2",version="v1.0")
@LKAParam(type=User.class,group="add")
@PostMapping("addUser2")
public Map<String,Object> addUser2(User user,@RequestHeader("x_token")String x_token) {
Map<String,Object> map = new HashMap<>();
map.put("code", 200);
map.put("msg", "保存成功");
Map<String,Object> map2 = new HashMap<>();
map2.put("user", user);
map2.put("x_token", x_token);
map.put("result",map2);
return map;
}
效果圖(橫版樣式)：
6.@LKAGroup註解：
說明：該註解在方法入參對象上面使用
作用：用來指定入參對象屬性分組，LKADocument 可以自動掃描帶@LKAModel註解的對象，可以在方法上省略@LKAParam註解來描述入參對象，這時如果要指定分組就可以用@Group註解
案例：
@LKAMethod(value="新增用戶信息3",version="v1.0")
@PostMapping("addUser3")
public Map<String,Object> addUser3(@LKAGroup("add")User user,@RequestHeader("x_token")String x_token) {
Map<String,Object> map = new HashMap<>();
map.put("code", 200);
map.put("msg", "保存成功");
Map<String,Object> map2 = new HashMap<>();
map2.put("user", user);
map2.put("x_token", x_token);
map.put("result",map2);
return map;
}
效果圖，我們可以看到，和上一個案例效果是一樣的 (橫版樣式)：
案例2，複雜的對象入參:
/*地址對象*/
package com.xb.domain;
import com.lk.api.annotation.LKAModel;
import com.lk.api.annotation.LKAProperty;
@LKAModel("用戶地址對象")
public class Address {
@LKAProperty("地址ID")
private Integer id;
@LKAProperty(value="省份",groups= {"add2"},testData="湖南")
private String province;
@LKAProperty(value="城市",groups= {"add2"},testData="衡陽")
private String city;
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public String getProvince() {
return province;
}
public void setProvince(String province) {
this.province = province;
}
public String getCity() {
return city;
}
public void setCity(String city) {
this.city = city;
}
}
/*角色對象*/
package com.xb.domain;
import com.lk.api.annotation.LKAModel;
import com.lk.api.annotation.LKAProperty;
@LKAModel("角色對象")
public class Role {
@LKAProperty(value = "角色ID")
private Integer id;
@LKAProperty(value = "角色名稱",groups={"add2"},testData="管理員")
private String name;
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
}
/*user對象*/
package com.xb.domain;
import java.util.ArrayList;
import java.util.List;
import com.lk.api.annotation.LKAModel;
import com.lk.api.annotation.LKAProperty;
@LKAModel("用戶對象")
public class User {
@LKAProperty(value="用戶id",testData="3")
private Integer id;
@LKAProperty(value="用戶名稱",groups= {"add","add2"},testData="小紅")
private String name;
@LKAProperty(value="用戶郵箱",groups= {"add","add2"},testData="[email protected]")
private String email;
@LKAProperty(value="用戶年齡",groups= {"add-n","add2-n"},testData="28")
private Integer age;
@LKAProperty(type=Address.class,groups= {"add2"})
private Address address;
@LKAProperty(type=Role.class,isArray=true,groups= {"add2"})
private List<Role> roles = new ArrayList<>();
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getEmail() {
return email;
}
public void setEmail(String email) {
this.email = email;
}
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
public Address getAddress() {
return address;
}
public void setAddress(Address address) {
this.address = address;
}
public List<Role> getRoles() {
return roles;
}
public void setRoles(List<Role> roles) {
this.roles = roles;
}
}
/*測試接口*/
@LKAMethod(value="新增用戶信息4",version="v1.0",contentType=Lkad.JSON)
@PostMapping("addUser4")
public Map<String,Object> addUser4(@RequestBody @LKAGroup("add2")User user,@RequestHeader("x_token")String x_token) {
Map<String,Object> map = new HashMap<>();
map.put("code", 200);
map.put("msg", "保存成功");
Map<String,Object> map2 = new HashMap<>();
map2.put("user", user);
map2.put("x_token", x_token);
map.put("result",map2);
return map;
}
效果圖：
7.@LKAResposes和@LKARespose
說明：該註解在方法上面使用，只有該方法所屬類加了@LKAMethod註解纔會生效
作用：用來描述接口的響應字段
屬性：
value:字段說明
name:參數名稱
description:參數描述
dataType:參數類型 default "String"
isArray:是否是數組入參，取值true或false，默認爲false
parentName:父級字段名稱
type:出參model對象類型
group:出參model屬性分組
案例：略
四、LKADocument的高級應用
1.數組請求入參功能
2.複雜的請求、響應字段功能演示
3.文件上傳功能
4.修改接口參數備註信息添加和刪除功能
5.其它功能
更詳細的更全面的教程請觀看作者親自錄製的視頻教程，地址：