告别手写接口文档时代，比Swagger功能更强大的LKADocument接口文档管理框架诞生了！
发表于：2024-11-27 作者：热门IT资讯网编辑
编辑最后更新 2024年11月27日，更详细的更全面的教程请观看作者亲自录制的视频教程，地址：https://edu.51cto.com/sd/9cb7fLKADocument视频教程一、介绍在前后端分离，分工更加明细化的今天，为了减少前
更详细的更全面的教程请观看作者亲自录制的视频教程，地址：
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@LKADocumentpublic 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")@RestControllerpublic 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:字段类型,默认值为Stringrequired:是否必须，取值true或false,默认值为trueparamType:入参方式，取值query(params入参),header(请求头入参),path(请求地址入参),默认值为querytestData:测试数据isArray:是否是数组入参，取值true或false，默认为falsetype:对象入参，取值对象类型，如果入参是对象，上面除了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:字段类型,默认值为Stringrequired:是否必须，取值true或false,默认值为trueparamType:入参方式，取值query(params入参),header(请求头入参),path(请求地址入参),默认值为querytestData:测试数据isArray:是否是数组入参，取值true或false，默认为falsetype:嵌套对象入参，取值对象类型，如果入参是对象，上面除了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，默认为falseparentName:父级字段名称type:出参model对象类型group:出参model属性分组案例：略
四、LKADocument的高级应用
1.数组请求入参功能
2.复杂的请求、响应字段功能演示
3.文件上传功能
4.修改接口参数备注信息添加和删除功能
5.其它功能
更详细的更全面的教程请观看作者亲自录制的视频教程，地址：
https://edu.51cto.com/sd/9cb7fLKADocument视频教程