更详细的更全面的教程请观看作者亲自录制的视频教程,地址:
https://edu.51cto.com/sd/9cb7f
LKADocument视频教程
在前后端分离,分工更加明细化的今天,为了减少前端和后台开发人员的沟通成本,能够让他们做到并行开发,同时也能保证前端和后端开发人员所看到的接口文档的一致性,即时性,以此来大大提高工作效率。所以出现了一些非常优秀的接口管理工具,具有代表性的像Swagger,因为它能够通过注解或yml和JSON描述文件来自动生成接口文档。但是我觉得它不管是在配置过程还是正常使用过程都不是特别好用,特别是对对象参数和复杂的参数注释很不友好,对前端开发人员更不友好。
所以,LKADocument诞生了!LKADocument它也是一款基于Spring Web能够全自动生成接口文档管理的JAVA后台框架,没错!确实和swagger很像,但比swagger更加强大和智能,总体来说,要比swagger配置更简单,使用起来更方便,在参数注释和UI展示这一块功能更加强大,任何复杂的请求参数和响应参数都能够用注解描述出来,同样也支持接口在线调试,支持rest风格的接口。UI操作界面更符合中国程序员的口味,同时对前端和后端开发人员更加友好,特别是后端开发人员。先来几张图片大家感受一下强大的功能:
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,如果配置没有问题可以看下如下界面:
注意:目前用火狐和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("123@qq.com");
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("123@qq.com");
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="321@qq.com"),
@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="456@qq.com")
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="456@qq.com")
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属性分组
案例:略
1.数组请求入参功能
2.复杂的请求、响应字段功能演示
3.文件上传功能
4.修改接口参数备注信息添加和删除功能
5.其它功能
更详细的更全面的教程请观看作者亲自录制的视频教程,地址:
https://edu.51cto.com/sd/9cb7f
LKADocument视频教程
免责声明:本站发布的内容(图片、视频和文字)以原创、转载和分享为主,文章观点不代表本网站立场,如果涉及侵权请联系站长邮箱:is@yisu.com进行举报,并提供相关证据,一经查实,将立刻删除涉嫌侵权内容。