更详细的更全面的教程请观看作者亲自录制的视频教程，地址：
https://edu.51cto.com/sd/9cb7fLKADocument视频教程
一、介绍
在前后端分离，分工更加明细化的今天，为了减少前端和后台开发人员的沟通成本，能够让他们做到并行开发，同时也能保证前端和后端开发人员所看到的接口文档的一致性，即时性，以此来大大提高工作效率。所以出现了一些非常优秀的接口管理工具，具有代表性的像Swagger，因为它能够通过注解或yml和JSON描述文件来自动生成接口文档。但是我觉得它不管是在配置过程还是正常使用过程都不是特别好用，特别是对对象参数和复杂的参数注释很不友好，对前端开发人员更不友好。
所以，LKADocument诞生了！LKADocument它也是一款基于Spring Web能够全自动生成接口文档管理的JAVA后台框架，没错！确实和swagger很像，但比swagger更加强大和智能，总体来说，要比swagger配置更简单，使用起来更方便，在参数注释和UI展示这一块功能更加强大，任何复杂的请求参数和响应参数都能够用注解描述出来，同样也支持接口在线调试，支持rest风格的接口。UI操作界面更符合中国程序员的口味，同时对前端和后端开发人员更加友好，特别是后端开发人员。先来几张图片大家感受一下强大的功能：
二、添加LKADocument插件到SpringBoot项目
1.在项目根路径创建一个lib文件夹，把LKADocument对应的jar复制进去(目前还没有放到maven中央或镜像仓库，故采用本地引入的方式)：
2.在pom.xml添加依赖引入:
LKADocument
LKADocument
0.0.1-SNAPSHOT
system
${project.basedir}/lib/LKADocument-0.0.1-SNAPSHOT.jar
3.在application.yml添加配置:
lkad:
basePackages: com.xb #指定扫描的包路径，多个包路径可以","隔开
projectName: lkad测试项目 #项目名称
description: 基于LKADocument工具自动生成的接口文档 #项目描述
enabled: true #是否开启lkad自动生成接口文档,默认为true4.项目启动类加上@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，如果配置没有问题可以看下如下界面：
注意：目前用火狐和Chrome浏览器能正常打开，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 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 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 addUser2(User user,@RequestHeader("x_token")String x_token) {
Map map = new HashMap<>();
map.put("code", 200);
map.put("msg", "保存成功");
Map 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 addUser3(@LKAGroup("add")User user,@RequestHeader("x_token")String x_token) {
Map map = new HashMap<>();
map.put("code", 200);
map.put("msg", "保存成功");
Map 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 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 getRoles() {
return roles;
}
public void setRoles(List roles) {
this.roles = roles;
}
}
/*测试接口*/
@LKAMethod(value="新增用户信息4",version="v1.0",contentType=Lkad.JSON)
@PostMapping("addUser4")
public Map addUser4(@RequestBody @LKAGroup("add2")User user,@RequestHeader("x_token")String x_token) {
Map map = new HashMap<>();
map.put("code", 200);
map.put("msg", "保存成功");
Map 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.其它功能
更详细的更全面的教程请观看作者亲自录制的视频教程，地址：
https://edu.51cto.com/sd/9cb7fLKADocument视频教程
后话：本来这套视频本来想免费的，但我发现作为一个30多岁的大龄程序员，存款不超5位数。条件不允许我免费啊，现实是我只是一个带着一丝悲凄的程序员罢了。你们就当是请我喝杯咖啡吧。最后希望大家多多支持我，你们支持我是奋斗下去的动力！