1. 前言

Lkadoc接口文档生成框架开源以来，备受好评，后期还会给lkadoc整个开源社区，方便大家讨论和解决问题。Lkadoc的前身叫lkadocument，个人感觉名字太长，不利于工具的推广，所以简化了名称为Lkadoc。名称的含义也很简单，Lk是我名字首字母，a代表接口（api）的意思，doc当然就是指文档（document）了。如果读者有使用过lkadocument的经验就知道，lkadocument的版本分奇数和偶数两种版本，奇数版自带导出PDF所需字体，所以jar包比较大，偶数版没有带字体文件，体积较小。 lkadocument发布最新版为1.1.4，也是lkadocument最后一个版本，以后发布的版本工具名称改为lkadoc。因为增加的功能比较多，特别是新增了数据校验等激动人心的功能，所以lkadoc第一个版本直接升级到1.2.0，从1.2.0版开始就不区分奇偶版了，统一为不带字体的，这样jar包体积更少，大家在下载使用时更顺畅。但需要检查系统是否存在simsun.ttc字体，如果系统没有这个字体的话，导出PDF文档中文不能正确显示。 windows系统字体路径：C:/Windows/fonts/simsun.ttc，linux系统字体路径：/usr/share/fonts/win/simsun.ttc，mac系统字体路径：/System/Library/Fonts/simsun.ttc。

2. 介绍

Lkadoc是一款能够基于注解自动生成带调试功能的接口文档工具，生成的UI界面简约大方，对接口描述一目了然，自面世以来深受大家的推崇和喜爱，大大提高了后端开发效率，减小了前端和后端接口对接的沟通成本。很多以前使用swagger的读者改成了lkadoc方案，反应都说比swagger好用太多了。下面简单的对lkadoc特色功能介绍一下： - 支持导出成PDF和MD格式的文档 - 支持在线调试API（包括数组入参、上传文件、文件下载均支持） - 支持对接口进行压力测试 - 支持多项目接口文档聚合展示 - 支持自动识别对象入参或出参，可实现接口零注解 - 支持任何复杂的对象参数结构，理论上支持最大10层的参数结构嵌套（防止嵌套出现死循环，做了10层限制） - 支持一条注解描述“多个”参数，支持一条注解描述“多层”参数结构（大大简化注解数量） - 支持JSON格式化展示请求参数和响应参数（参数结构一目了然，减少前后端沟通成本，减少失误） - 支持版本控制新接口标记显示（方便定位新接口） - 支持接口名称和参数添加标签（特殊说明可以加标签提示，减少前后端沟通成本） - 支持对象属性分组（包括父类继承属性） - 支持对请求参数进行数据校验（支持正则匹配、非空、非null、集合非空、字符串长度、数值范围等常用校验规则，如果关闭接口文档功能不会影响数据校验功能。） - 更多功能...

版本更新说明：

lkadoc 1.2.4于2020年9月24日发布：

修复项目在使用shiro等框架时application/json方式对象参数数据校验失效的BUG
修复map集合入参时在自动检测参数paramType类型报数组越界异常的BUG
优化一条注解描述多个参数时，如果哪个参数无需数据校验可在valids属性中用空字符串“”表示
优化入参value属性值前面加“n~”代表非必传参数。例如：优化之前: @LKAParam(values={"姓名","年龄"},testDatas={"张三","22"},requireds={true,false}) @LKAProperty(value="id主键",testData="1001",required=false)
优化之后: @LKAParam(values={"姓名^张三","n~~年龄^22"}) @LKAProperty(value="n~~id主键^1001")

lkadoc 1.2.3于2020年9月15日发布：

修复项目不能带中文路径的BUG
修复找不到文件路径报空指针的BUG
修复UI界面给父级节点添加标签异常BUG
增加LKAMethod注解token属性，用于标识该接口是否需要token授权验证
增加UI界面选项页功能
拆分lkadoc为api、annotation两个模块。可分别使用以下maven配置：

<dependency>
<groupId>com.github.liukaitydn</groupId>
<artifactId>lkadoc-annotations</artifactId>
<version>1.2.3</version>
</dependency>
<dependency>
<groupId>com.github.liukaitydn</groupId>
<artifactId>lkadoc-api</artifactId>
<version>1.2.3</version>
</dependency>

其中lkadoc-annotations是单独的一个模块，如果工程只用到注解可以只添加lkadoc-annotations模块即可。lkadoc-api模块依赖lkadoc-annotations模块，当然工程只添加lkadoc-api模块的maven配置也会自动把lkadoc-annotations模块引入到当前工程。

lkadoc 1.2.2 修复1.2.1不能导出pdf和md的功能

lkadoc 1.2.1 于2020年8月5日发布(有bug，导出有问题，请使用1.2.2版)：

增加md格式文档导出
增加对父节点参数名称的复制功能
增加对父节点参数添加标签功能，如果父节点标签为删除标签，那么在调试该接口时不会把该父节点参数及所有子参数传到后台

3. 准备工作

3.1 在SpringBoot项目中引入两个jar包

<!--Lkadoc包-->
<dependency>
<groupId>com.github.liukaitydn</groupId>
<artifactId>lkadoc-api</artifactId>
<version>1.2.3</version>
</dependency>
<!--itextpdf包，把接口信息导出成PDF文档是基于itextpdf来实现的，所以要引入这个包-->
<dependency>
<groupId>com.itextpdf</groupId>
<artifactId>itextpdf</artifactId>
<version>5.5.13</version>
</dependency>

3.2 在SpringBoot项目启动类上加上@LKADocument注解

@LKADocument@SpringBootApplicationpublicclassLKADemoApplication {
publicstaticvoidmain(String[] args) {
SpringApplication.run(LKADemoApplication.class, args);
}
}

3.3 在application.yml文件中添加如下配置

lkad:
#要扫描接口的包路径，多个用","号隔开，指定父包可以扫描所有父包下的子包（必配）basePackages: com.lkad.api#项目名称（选配）projectName: Lkadoc测试项目#项目描述（选配）description: 智能、便捷、高效#要聚合的项目地址，"-"前面是项目名称（可省略），后面是项目的地址（也可以用域名），多个用","号隔开，用来聚合其它项目的接口信息，可以在UI界面切换（选配）serverNames: 租房系统-192.168.0.77:9010,缴费系统-192.168.0.77:8888#项目的版本号（选配）version: 1.0#接口文档启动开关,true是开启，false是禁用,默认为开启，此开关对数据校验没有影响（选配）enabled: true

或者在启动类注解@LKADocument上设置如下属性（和上面配置二选一即可,效果一模一样）

@LKADocument(basePackages="com.lkad.api",projectName="Lkadoc测试项目",description="智能、便捷、高效",version="1.0",serverNames="租房系统-192.168.0.77:9010,缴费系统-192.168.0.77:8888",enabled=true)
@SpringBootApplicationpublicclassLKADemoApplication {
publicstaticvoidmain(String[] args) {
SpringApplication.run(LKADemoApplication.class,args);
}
}

3.4 准备测试代码

packagecom.lkad.api;
importjava.util.HashMap;
importjava.util.Map;
importorg.springframework.web.bind.annotation.PostMapping;
importorg.springframework.web.bind.annotation.RequestMapping;
importorg.springframework.web.bind.annotation.RestController;
importcom.lk.api.annotation.*;
@LKAType(value="第一个测试类")
@RestController@RequestMapping("lkadocument/demo")
publicclassLKADemoController {
@LKAMethod(value="登录")
@LKAParam(names= {"name","pwd"},values= {"用户名","密码"})
@LKARespose(names= {"code","msg"},values= {"状态码","消息"})
@PostMapping("login")
publicMap<String,Object> login(Stringname,Stringpwd) {
Map<String,Object> map = newHashMap<>();
map.put("code",200);
map.put("msg","登录成功，欢迎"+name+"光临本系统");
returnmap;
}
}

3.5 打开浏览器，输入地址http://127.0.0.1:8080/lkadoc.html 查看效果如下：

4. 基础入门

4.1 LKAType注解

LKAType注解:用来描述接口对应的处理类#常用属性：value:类的作用（必配）description:类的描述（选配）hidden:是否在UI界面隐藏该类的信息，默认为false（选配）

*注意：Lkadoc为swagger大部分注解做了兼容处理，只需修改引入的包路径为com.lk.api.即可

4.2 LKAMethod注解

LKAMethod注解:用来描述接口信息#常用属性：value:接口的作用（必配）description:接口的描述（选配）contentType:请求头ContentType类型，默认为application/x-www-form-urlencoded（选配）author:作者（选配）createTime:接口创建时间（选配）updateTime:接口修改时间（选配）hidden:是否在UI界面隐藏该接口，默认为false（选配）version:接口版本号，如果项目版本号相同，在UI界面会标记为新接口（选配）download:是否是下载的方法，默认是false（选配）token:是否需要token授权验证，默认是true（选配）

4.2.1 LKAType和LKAMethod演示代码

packagecom.lkad.api;
importjava.util.HashMap;
importjava.util.Map;
importorg.springframework.web.bind.annotation.PostMapping;
importorg.springframework.web.bind.annotation.RequestMapping;
importorg.springframework.web.bind.annotation.RestController;
importcom.lk.api.annotation.*;
importcom.lk.api.constant.ContentType;
@LKAType(value="第一个测式类",description="用来演示LKADocument",hidden=false)
@RestController@RequestMapping("lkadocument/demo")
publicclassLKADemoController {
@LKAMethod(value="登录",description="用户登录验证",contentType=ContentType.URLENCODED,
author="liukai",hidden=false,version="1.0",download=false,createTime="2020-7-20",updateTime="2020-7-20")
@LKAParam(names= {"name","pwd"},values= {"用户名","密码"})
@LKARespose(names= {"code","msg"},values= {"状态码","消息"})
@PostMapping("login")
publicMap<String,Object> login(Stringname,Stringpwd) {
Map<String,Object> map = newHashMap<>();
map.put("code",200);
map.put("msg","登录成功，欢迎"+name+"光临本系统");
returnmap;
}
}

效果图：

4.3 运用版本号快速定位新接口

大家应该还有印象，在用@LKADocument注解配置项目信息时有一个version属性用来设置项目的版本号，然后@LKAMethod注解也有一个version属性用来设置接口的版本号，在实际工作中，往往一个项目版本升级并不代表所有接口都需要升级，也可能会增加一些新接口。那么我们怎么才能在众多的接口中定位哪一个接口是新接口或最新修改的接口呢？很简单，我们只需把新接口或最新修改的接口的@LKAMethod注解version属性的版本值设置和@LKADocument注解的version属性的版本值设置成一致就可以了，这样Lkadoc会用红色标记出新接口。那么后端在和前端同事对接口时就可以很快定位哪些是新接口了。

4.3.1 案例：

packagecom.lkad.api;
importorg.springframework.web.bind.annotation.GetMapping;
importorg.springframework.web.bind.annotation.RestController;
importcom.lk.api.annotation.*;
/** * 在这里我们再准备一个测试 */@LKAType("Hello类")
@RestControllerpublicclassHelloController {
/** * 注意：这个接口并没有设置version版本值，但4.2.1那个测试代码的登录接口设置了version值和项目的 * version值一致，我们对比一下看看两个接口在UI展示有什么不一样。 */@LKAMethod(value="Hello方法")
@GetMapping("hello")
publicStringhello() {
return"hello Lkadoc!";
}
}

效果图：

4.4 LKAParam和LKAParams注解

4.4.1 常用属性解析

LKAParam/LKAParams:描述请求参数信息，LKAParams注解可以包含多个LKAParam注解，用来描述多个请求参数。#常用属性,带s复数属性代表可以设置多个参数,但要注意参数顺序。带s和不带s设置时只能二选一name/names:参数名称（用name设置参数名称时必配;用names设置参数名称时可省略，但JDK版本要1.8以上，编译的时候还要加上–parameters参数，这样Lkadoc可自动获取到参数名称,否则必配）#例如:#单个参数配置:#@LKAParam(name="name",...)#多个参数配置:#@LKAParam(names={"name","pwd","age"},...)//这里如果和接口入参顺序一样，可省略不用配置#或者#@LKAParams({#@LKAParam(name="name",...),#@LKAParam(name="pwd",...),#@LKAParam(name="age",...)#})value/values:参数作用（必配）#例如:#单个参数配置:#@LKAParam(name="name",value="用户名")#多个参数配置:#@LKAParam(values={"用户名","密码","年龄"})//这里把names省略了(注意入参顺序)，可自动获取#或者#@LKAParams({#@LKAParam(name="name",value="用户名"),#@LKAParam(name="pwd",value="密码"),#@LKAParam(name="age",value="年龄")#})description/descriptions:参数的描述（选配）#例如：和value/values用法一样（略）dataType/dataTypes:数据类型，（用dataType配置时默认值String.class;用dataTypes配置时可自动获取参数的数据类型，可省略不配置，但要注意参数的顺序。）（选配）#例如:#单个参数配置:#@LKAParam(name="name",value="用户名",dataType=String.class)//这里可省略，因为默认是String#多个参数配置:#@LKAParam(...,dataTypes={String.class,String.class,Integer.class},...) //这里如果和接口入参顺序和数量一致的话，也可以省略，可自动获取#或者#@LKAParams({#@LKAParam(name="name",value="用户名",dataType=String.class),#@LKAParam(name="pwd",value="密码",dataType=String.class),#@LKAParam(name="age",value="年龄",dataType=Integer.class)#})required/requireds:是否必传，默认为true（选配）(更简便的用法是在参数名后加"-n"代表不是必传，不加默认是必传)#例如:#@LKAParam(name="name",value="用户名",required=false)#或者#@LKAParam(name="name-n",value="用户名") //参数名称后面加"-n"代表不是必传，不加默认是必传paramType/paramTypes:参数位置，query、header、path三选一，（用paramType配置时默认为query;用paramTypes配置时Lkadoc可根据参数注解@PathVariable、@RequestHeader自动获取参数位置，可省略不配）isArray/isArrays:是否是集合或数组，默认false（选配）testData/testDatas:测试数据（选配）(更简便的用法是在value/values后面的"^"符号后面加上测试数据)#例如:#@LKAParam(name="name",value="用户名",required=false,testData="张三")#或者#@LKAParam(name="name-n",value="用户名^张三") //在value/values后面的"^"符号后面加上测试数据type:入参对象类型（当接口请求参数是一个对象时使用，但一般不需要设置，可自动识别）group:和type配合使用，对象参数分组，可过滤没必要的参数#数据校验相关属性（后面会详细讲解）valids:数据校验常用规则或正则匹配msgs:数据校验消息range:数值范围限制判断size:集合、数组大小限制判断length:字符串长度限制判断

4.4.2 测试代码

/*** 在LKADemoController类中加一个测试接口getUsers* 说明：* dataType和paramType均可自动获取,所以可省略不配* required在name后用"-n"代替，所以可以省略不配* testData可在value后面的"^"加上，所以可以省略不配*/@LKAMethod("获取用户信息")
@LKAParam(names= {"name","age-n","roleType-n","token"},values= {"用户名^张三","年龄^22","角色类型^1","授权token^aa"})
@LKARespose(names= {"code","msg","data"},values= {"状态码","消息","数据"})
@PostMapping("getUsers/{roleType}")
publicMap<String,Object> getUsers(
Stringname,
Integerage,
@PathVariable("roleType")IntegerroleType,//path参数@RequestHeader("token")Stringtoken) { //header参数Map<String,Object> map = newHashMap<>();
map.put("code",200);
map.put("msg","获取信息成功");
map.put("data","姓名："+name+",年龄："+age+",角色类型："+(roleType==1?"经理":"员工")+",token："+token);
returnmap;
}

效果图:

4.5 调试API功能

4.5.1 测试API请求

Lkadoc支持对单个接口进入调试，我们只需要准备好请求参数的测试数据，然后点击"测试API请求"按钮，就可以在调试窗口看到结果信息了。

4.5.2 压力测试

我们可以通过选择执行方式来决定接口采用"同步"还是"异步"执行，如果选择"同步"测试，可以选择执行次数，和时间间隔，这样可以模拟对接口进行压力测试。如果选择"异步"测试，可以选择执行次数，这样可以模拟对接口进行并发测试。所有测试结果会打印在调试窗口中。

4.6 全局token锁定

我们在调试需要token授权的接口时,需要在每个需要授权接口的请求头带上一个类似token的参数，调试时非常不方便，所以Lkadoc提供了一个可以给全局接口锁定一个请求头参数，这样就不需要在每一个需要授权的接口中去设置这个授权参数了。

4.7 数组传参

4.7.1 注意事项

数组传参注意事项
1.isArray要设置成true，代表是数组
2.参数类型dataType一定要是一个数组类型，例如：String[].class
3.接口调试时要勾选“阻止深度序列化”

4.7.2 测试代码

/**在LKADemoController类中加一个测试接口*/@LKAMethod(value="数组传参")
@LKAParam(name="ids",value="用户id",isArray=true,dataType=String[].class)
@LKARespose(names= {"code","msg","data"},values= {"状态码","消息","数据"})
@PostMapping("arrTest")
publicMap<String,Object> arrTest(String[] ids) {
Stringarr = "";
if(ids != null) {
for (Stringid : ids) {
if("".equals(arr)) {
arr = id;
}else {
arr = arr+","+id;
}
}
}
Map<String,Object> map = newHashMap<>();
map.put("code",200);
map.put("msg","获取信息成功");
map.put("data","ids="+arr);
returnmap;
}

效果图:

4.8 文件上传

4.8.1 注意事项

文件上传(支持单个或批量上传)注意事项
1.如果是批量上传isArray要设置成true，代表是数组
2.单个文件上传dataType类型要设置成"MultipartFile.class",批量上传dataType参数类型要设置成“MultipartFile[].class”
3.前端需要把from表单的enctype属性设置成'multipart/form-data'
4.请求类型必须是"post"

4.8.2 测试代码

/**在LKADemoController类中加一个测试接口*/@LKAMethod(value="文件批量上传",contentType=ContentType.FORMDATA)
@LKAParam(name= "files",value="上传文件",isArrays= true,dataType=MultipartFile[].class)
@LKARespose(names= {"code","msg","data"},values= {"状态码","消息","数据"})
@PostMapping("fileUpload")
publicMap<String,Object> fileUpload(MultipartFile[] files) {
StringfileNames = "";
if(files != null) {
for (MultipartFilef : files) {
if("".equals(fileNames)) {
fileNames = f.getOriginalFilename();
}else {
fileNames = fileNames + ","+f.getOriginalFilename();
}
}
}
//上传后续业务处理：略Map<String,Object> map = newHashMap<>();
map.put("code",200);
map.put("msg","上传文件成功!");
map.put("data","文件名："+fileNames);
returnmap;
}

效果图:

4.9 文件下载

4.9.1 注意事项

LKAMethod注解里面的download属性要设置成true,代表是下载的接口

4.9.2 测试代码

/**在LKADemoController类中加一个测试接口*/@LKAMethod(value="文件下载",download=true)
@PostMapping("fileDownload")
publicvoidfileDownload(HttpServletResponseresponse) throwsException {
Stringpath = "D:\\test.txt";
Filefile = newFile(path);
Stringext = file.getName().substring(file.getName().lastIndexOf(".") + 1).toUpperCase();
InputStreamfis = newBufferedInputStream(newFileInputStream(path));
byte[] buffer = newbyte[fis.available()];
fis.read(buffer);
fis.close();
response.reset();
response.addHeader("Content-Disposition", "attachment;filename=" + newString(file.getName().getBytes()));
response.addHeader("Content-Length", "" + file.length());
OutputStreamtoClient = newBufferedOutputStream(response.getOutputStream());
response.setContentType("application/octet-stream");
toClient.write(buffer);
toClient.flush();
toClient.close();
}

5. 高级应用

5.1 LKAModel注解

LKAModel注解:用来标识需要扫描的实体类

5.2 LKAProperty注解

LKAProperty注解:用来描述实体类的属性信息#常用属性value:属性的作用description:属性的描述hidden:是否在UI界面隐藏该属性，默认为false（选填）testData:测试数据（选配）(更简便的用法是在value后面的"^"符号后面加上测试数据)required:是否必传，默认为true（选配）(更简便的用法是在groups属性里面的组名后面加"-n"代表不是必传，不加默认是必传)isArray:是否是数组或集合type:当属性为对象类型时，需用type来指定groups:用来进行参数分组#数据校验相关属性（后面会详细讲解）valids:数据校验常用规则或正则匹配msgs:数据校验消息range:数值范围限制判断size:集合、数组大小限制判断length:字符串长度限制判断

5.3 基本对象入参

5.3.1 注意事项

当我们入参是一个对象时，如果该对象上有@LKAModel注解，并且它的属性上有@LKAProperty注解，那么Lkadoc会去自动扫描这个对象信息，我们无需在接口上加额外的注解去描述对象参数。这样如果我们用对象去操作入参的话，可以大大减少接口上的注解数量，显得更加简洁。

5.3.2 测试代码

/**准备一个角色对象*/@LKAModelpublicclassRole {
@LKAProperty(value="角色id^1")
privateIntegerid;
@LKAProperty(value="角色^名称")
privateStringname;
publicIntegergetId() {
returnid;
}
publicvoidsetId(Integerid) {
this.id = id;
}
publicStringgetName() {
returnname;
}
publicvoidsetName(Stringname) {
this.name = name;
}
}
/**在LKADemoController类中加一个测试接口*/@LKAMethod("基本对象入参")
@GetMapping("getRole")
publicRolegetRole(Rolerole) {
returnrole;
}

效果图：

5.4 复杂的对象入参

5.4.1 注意事项

1.复杂的对象需把@LKAMethod注解的contentType属性设置为"application/json"
2.如果contentType="application/json"，需在接收对象参数前面加@RequestBody注解
3.如果contentType="application/json"，那么接口的请求类型不能是get
4.如果对象参数是实体类型需要用@LKAProperty注解的type属性来指定类型
5.如果对象参数是数组或List或Set集合需要把@LKAProperty注解的isArray设置成true

5.4.2 测试代码

/**再增加两个对象address和User，加上之前Role一共有3个对象*/@LKAModelpublicclassAddress {
@LKAProperty(value="地址ID^1")
privateIntegerid;
@LKAProperty(value="地址信息^深圳市龙华区")
privateStringinfo;
....get/set方法.....
}
@LKAModelpublicclassUser {
@LKAProperty(value="用户ID",hidden=true)//hidden设置成true，该属性不会在UI界面展示privateIntegerid;
@LKAProperty(value="用户名称^张三")
privateStringname;
@LKAProperty(value="年龄^20",required=false,description="范围0-120")
privateStringage;
@LKAProperty(value="角色对象",type=Role.class)
privateRolerole;
@LKAProperty(value="用户爱好^运动",isArray=true)
privateString[] likes;
@LKAProperty(value="地址信息",isArray=true,type=Address.class)
privateList<Address> addresses;
....get/set方法.....
}
/**在LKADemoController类中加一个测试接口*/@LKAMethod(value="复杂的对象传参",contentType=ContentType.JSON)
@PostMapping("addUser")
publicUseraddUser(@RequestBodyUseruser) {
returnuser;
}

效果图1：

效果图2：

5.5 对象参数分组

	我们感受到了用对象接收请求参数更具便利性，那怎么去过滤对象属性呢？例如：有一个查询接口，只用到user对象的name、age和addresses属性对象的info参数，但对于前端的友好度，我们不需要展示所有对象属性到UI界面，这时我们就可以用分组来实现.

5.5.1 注意事项

1.分组可以用@LKAProperty注解的groups属性来设置组名
2.一个属性可以属于多个组，组名不能重复
3.组名没有任何限制，只要不是空白的字符串即可
4.如果用到嵌套对象里面属性，嵌套对象名称和对应属性上都要设置相同的组名
5.入参对象需要用@LKAGroup注解来指定对象是哪组参数用来作为入参

5.5.2 测试代码

/**这里我们设置一个组名叫addUser（和接口名保持一致，方便区分）,分别用到user对象的name参数、age参数和addresses属性对象的info参数*/@LKAModelpublicclassUser {
@LKAProperty(value="用户ID",hidden=true)//hidden设置成true，该不会在UI界面展示privateIntegerid;
@LKAProperty(value="用户名称^张三",groups= {"addUser"})
privateStringname;
@LKAProperty(value="年龄^20",required=false,description="范围0-120",groups= {"addUser"})
privateStringage;
@LKAProperty(value="角色对象",type=Role.class)
privateRolerole;
@LKAProperty(value="用户爱好^运动",isArray=true)
privateString[] likes;
@LKAProperty(value="地址信息",isArray=true,type=Address.class,groups= {"addUser"})
privateList<Address> addresses;
.......get/set.......
}
@LKAModelpublicclassAddress {
@LKAProperty(value="地址ID",testData="5")
privateIntegerid;
@LKAProperty(value="地址信息",testData="深圳市龙华区",groups= {"addUser"})
privateStringinfo;
.......get/set.......
}
/**在LKADemoController类中的addUser接口入参对象User前面加一个注解@LKAGroup("addUser")*/@LKAMethod(value="复杂的对象传参",contentType=ContentType.JSON)
@PostMapping("addUser")
publicUseraddUser(@RequestBody@LKAGroup("addUser") Useruser) {
returnuser;
}

效果图：

5.6 响应参数的基本用法

5.6.1 LKARespose/LKAResposes注解

LKARespose/LKAResposes:描述响应参数信息，LKAResposes注解可以包含多个LKARespose注解，用来描述多个响应参数。#常用属性name/names:参数名称，和type参数二选一（必填）#例如:#单个参数配置:#@LKARespose(name="code",...)#多个参数配置:#@LKARespose(names={"code","msg","data"},...)#或者#@LKAResposes({#@LKARespose(name="code",...),#@LKARespose(name="msg",...),#@LKARespose(name="data",...)#})value/values:参数作用（必填）description/descriptions:参数的描述（选填）dataType/dataTypes:参数数据类型，默认String.class（选填）isArray/isArrays:是否是集合或数组，默认false（选填）type:出参对象类型，和name/names参数二选一（必填）group:和type配合使用，对象参数分组，可过滤没必要的参数（选填）#父参数parentName:父参名称（选填）parentValue:父参作用（选填）parentDescription:父参描述（选填）parentIsArray:父参是否是数组或集合（选填）#爷参数grandpaName:爷参名称（选填）grandpaValue:爷参作用（选填）grandpaDescription:爷参描述（选填）grandpaIsArray:爷参是否是数组或集合（选填）

5.6.2 简单Map集合出参

/** 我们回过头来看之前用过的一个接口-获取用户信息，这个接口响应参数是一个Map集合,这个Map集合结构比较简单，就 三个不带嵌套结构的属性，这个描述非常简单，一条@LKARespose注解搞定。*/@LKAMethod("获取用户信息")
@LKAParam(names= {"name","age-n","roleType-n","token"},values= {"用户名^张三","年龄^22","角色类型^1","授权token^aa"})
@LKARespose(names= {"code","msg","data"},values= {"状态码","消息","数据"})
@PostMapping("getUsers/{roleType}")
publicMap<String,Object> getUsers(
Stringname,
Integerage,
@PathVariable("roleType")IntegerroleType,//path参数@RequestHeader("token")Stringtoken) { //header参数Map<String,Object> map = newHashMap<>();
map.put("code",200);
map.put("msg","获取信息成功");
map.put("data","姓名："+name+",年龄："+age+",角色类型："+(roleType==1?"经理":"员工")+",token："+token);
returnmap;
}

效果图：

5.6.3 对象出参

/**如果出参是一个对象，且对象有加@LKAModel及属性有加@LKAProperty注解，那么Lkadoc会自动扫描该出参对象，我们可以看如下接口入参和出参都是一个对象，那么就不需注解去描述出参和入参了，非常简洁。*/@LKAMethod(value="复杂的对象传参",contentType=ContentType.JSON)
@PostMapping("addUser")
publicUseraddUser(@RequestBody@LKAGroup("addUser") Useruser) {
returnuser;
}

效果图1：

效果图2：

5.7 复杂的Map结构出参

5.7.1 说明

当一个接口出参是一个带嵌套结构的Map集合，我们该怎么描述它呢？如果涉及到对象，我们可以用@LKARespose注解的type属性去指定对象类型，如果涉及到多层嵌套结构，我们可以通过@LKARespose注解的parentXXX和grandpaXXX属性来指定。

5.7.2 测试代码

/**在LKADemoController类中加一个测试接口*/@LKAMethod(value="响应参数复杂的Map结构用法")
@LKAResposes({
@LKARespose(names= {"code","msg"},values= {"状态码","消息"}),
@LKARespose(name="total",value="总记录数",parentName="result",parentValue="响应数据"),
@LKARespose(type=User.class,parentName="users",parentIsArray=true,parentValue="用户对象列表",grandpaName="result")
})
@GetMapping("getMap")
publicMap<String,Object> getMap() {
Map<String,Object> map = newHashMap<>();
map.put("code",200);
map.put("msg","操作成功！");
Map<String,Object> data = newHashMap<>();
data.put("total",10);
List<User> users = newArrayList<>();
Useruser1 = newUser();
user1.setName("张三");
Useruser2 = newUser();
user2.setName("李四");
users.add(user1);
users.add(user2);
data.put("users",users);
map.put("result",data);
returnmap;
}

表格展示效果图：

JSON格式化展示效果图：

5.7.3 超过3层嵌套结构用法技巧

通过parentXXX和grandPaXXX相关属性用一条@LKARespose注解只能一次性描述1到3级节点，如果有5级或者10级节点该怎么办？也有解决办法，非常简单，但注解可能会比较多，例如有这么一个结构{a:{b:{c:{d:1}}}},我们可以这么做: @LKARespose(name="a",value="一级"), @LKARespose(name="b",value="二级",parentName="a"), @LKARespose(name="c",value="三级",parentName="b"), @LKARespose(name="d",value="四级",parentName="c")

5.7.4 测试代码

/**在LKADemoController类中加一个测试接口*/@LKAMethod(value="超过3层嵌套结构用法技巧")
@LKAResposes({
@LKARespose(name="a",value="一级"),
@LKARespose(name="b",value="二级",parentName="a"),
@LKARespose(name="c",value="三级",parentName="b"),
@LKARespose(name="d",value="四级",parentName="c")
})
@GetMapping("getMoreMap")
publicMap<String,Object> getMoreMap(){
Map<String,Object> mapa= newHashMap<>();
Map<String,Object> mapb= newHashMap<>();
Map<String,Object> mapc= newHashMap<>();
Map<String,Object> mapd= newHashMap<>();
mapa.put("a",mapb);
mapb.put("b",mapc);
mapc.put("c",mapd);
mapd.put("d",1);
returnmapa;
}

效果图：

5.8 复杂的对象结构出参

5.8.1 准备一个响应封装对象

@LKAModelpublicclassApiResult {
@LKAProperty(value="响应状态",description="200-正常,其它-错误")
privateStringcode;
@LKAProperty(value="响应消息")
privateStringmsg;
@LKAProperty(value="响应数据")
privateMap<String,Object> result = newHashMap<>();
privateApiResult() {}
publicstaticApiResultok() {
ApiResultres = newApiResult();
returnres;
}
publicApiResultput(Stringkey,Objectvalue) {
this.result.put(key, value);
returnthis;
}
..........get/set方法...........
}

5.8.2 准备一个测试接口

/**这个方法其实和上面5.7.2那个测试方法响应参数结构是一样的，不一样的地方是一个是Map,一个是ApiResut对象。但是我们发现这个方法在响应参数描述是少用一个注解：@LKARespose(names= {"code","msg"},values= {"状态码","消息"})这是因为ApiResult对象已经通过@LKAProperty注解描述过"code","msg"属性了，Lkadoc会去自动扫描带有@LKAModel注解的响应对象。还有如果@LKARespose注解描述的参数和对象里面的属性一致的话，@LKARespose注解描述的参数会覆盖掉对象里面的属性*/@LKAMethod(value="响应参数复杂的对象结构用法")
@LKAResposes({
@LKARespose(name="total",value="总记录数",parentName="result",parentValue="响应数据"),
@LKARespose(type=User.class,parentName="users",parentIsArray=true,parentValue="用户对象列表",grandpaName="result")
})
@PostMapping("getObj")
publicApiResultgetObj() {
List<User> users = newArrayList<>();
Useruser1 = newUser();
user1.setName("张三");
Useruser2 = newUser();
user2.setName("李四");
users.add(user1);
users.add(user2);
returnApiResult.ok().put("total",10).put("users",users);
}

效果图：

5.9 响应参数对象属性分组

@LKARespose注解的group属性也可以实现响应参数分组，使用原理和请求参数分组是一样的。

5.9.1 准备一个对象属性过滤器

/**对象字段过滤器(为了模拟真实业务场景加了这个工具，与Lkadoc没有任何关联。)这里用到了一个fastJson的jar工具<dependency> <groupId>com.alibaba</groupId> <artifactId>fastjson</artifactId> <version>1.2.31</version></dependency>*/publicclassFieldsFilter {
publicstatic<T> Map<String,Object> filter(Tobject,List<String> fieldNames){
if(object == null){
returnnull;
}
Map<String,Object> map = newHashMap<>();
//把object转换成json对象JSONObjectjson = JSON.parseObject(JSON.toJSONString(object));
//判断要过滤的字段for (StringfieldName : fieldNames) {
Objectvalue = json.get(fieldName);
map.put(fieldName,value);
}
returnmap;
}
publicstatic<T> List<Map<String,Object>> filter(List<T> list,List<String> fields){
if(list == null || list.size() == 0){
returnnull;
}
List<Map<String,Object>> maps = newArrayList<>();
for (Objectobject : list) {
Map<String, Object> filter = filter(object, fields);
maps.add(filter);
}
returnmaps;
}
}

5.9.2 给对象属性分组

/**我们可以看到，这里一共有两个分组，一个是'addUser'给之前一个叫addUser接口入参数使用的，另一个是'getObj'这个就是我们等下要演示响应对象属性分组用的。'getObj'组包含的属性有User对象的用户名称、年龄、用户爱好，Role对象的角色名称。*/@LKAModelpublicclassUser {
@LKAProperty(value="用户ID",hidden=true)//hidden设置成true，该不会在UI界面展示privateIntegerid;
@LKAProperty(value="用户名称^张三",groups= {"addUser","getObj"})
privateStringname;
@LKAProperty(value="年龄^20",required=false,description="范围0-120",groups= {"addUser","getObj"})
privateStringage;
@LKAProperty(value="角色对象",type=Role.class,groups= {"getObj"})
privateRolerole;
@LKAProperty(value="用户爱好^运动",isArray=true,groups= {"getObj"})
privateString[] likes;
@LKAProperty(value="地址信息",isArray=true,type=Address.class,groups= {"addUser"})
privateList<Address> addresses;
..........get/set方法...........
}
@LKAModelpublicclassRole {
@LKAProperty(value="角色id^1")
privateIntegerid;
@LKAProperty(value="角色名称^经理",groups= {"getObj"})
privateStringname;
..........get/set方法...........
}

5.9.3 测试代码：

/**我们修改一下5.8.2的测试接口如下*/@LKAMethod(value="响应参数复杂的对象结构用法")
@LKAResposes({
@LKARespose(name="total",value="总记录数",parentName="result",parentValue="响应数据"),
@LKARespose(type=User.class,group="getObj",parentName="users",parentIsArray=true,parentValue="用户对象列表",grandpaName="result")
})
@PostMapping("getObj")
publicApiResultgetObj() {
List<User> users = newArrayList<>();
Useruser1 = newUser();
user1.setName("张三");
Useruser2 = newUser();
user2.setName("李四");
users.add(user1);
users.add(user2);
Rolerole = newRole();
role.setId(1);
role.setName("经理");
user1.setRole(role);
returnApiResult.ok().put("total",10).put("users", FieldsFilter.filter(users,Arrays.asList("name","age","likes","role")));
}

效果图：

6. 辅助功能

6.1 自定义接口或属性标签

如果我们要对某个特定的接口或属性增加一些说明信息，例如某个接口新增加了一个属性或修改了某个属性等等，这时我们可以在UI界面给接口或属性增加相应的标签即可。如果想删除该标签，就在接口或属性名称上再次双击就可以删除了。

6.2 导出PDF或MarkDown文档

如果需提供接口文档给第三方进行对接，可以使用Lkadoc的导出功能，Lkadoc支持导出标准化格式的PDF或MarkDown接口文档，功能非常强大，能满足大部分场景需求。（目前只支持导出本地项目的接口）导出PDF文档前需要检查系统是否存在simsun.ttc字体，如果系统没有这个字体的话，导出PDF文档中文不能正确显示。 windows系统字体路径：C:/Windows/fonts/simsun.ttc linux系统字体路径：/usr/share/fonts/win/simsun.ttc mac系统字体路径：/System/Library/Fonts/simsun.ttc

PDF效果截图：

MD效果截图

6.3 多项目聚合

当我们在使用微服务或多个子项目时，我们可以把多个项目的接口文档信息聚合到一个UI界面，只需要在@LKADocument注解配置serverNames属性即可： serverNames="租房系统-192.168.0.77:9010,缴费系统-192.168.0.77:8888" 多个项目之间用英文“,”号隔开，“-”符号左右是项目名称，右边是项目地址，也可以是域名，这样我们就可以在UI界面自由的在当前项目和配置好的其它项目切换接口信息了。

切换项目后的效果图：

6.4 UI风格切换

如果你对某一种UI界面颜色腻了，Lkadoc还支持切换不同风格的颜色，满足你不安分的心。

切换风格效果图：

7. 数据校验

数据校验是Lkadoc 1.2.0版新增加的模块，基于过滤器和拦截器实现的功能，支持query、path、header入参校验，能满足大部分业务场景。数据校验与接口文档是完全独立的两个模块，当把接口文档功能模块关闭并不会影响数据校验模块。

7.1 准备工作

需要在@LKADocument注解(在application文件中配置无效)把validation属性设置成true，代表开启数据校验功能，默认是关闭状态。例:@LKADocument(validation=true)

7.2 规则说明

#数据校验主要是依靠@LKAProperty和@LKAParam注解的如下属性实现的#一条@LKAParam注解描述多个参数，那么只能给每个参数加一个校验规则#一条@LKAParam注解描述一个参数，那么可以给每个参数加多个校验规则valids:数据校验常用规则或正则匹配，一个参数可设置多个规则#valids可接收一个数字串数组，Lkadoc里面预置了一个校验常量类V，里面的常量有：V.NOTNULL:对象、集合、数组、字符串、包装类不能为null，字符串可以为空V.NOTBLANK:字符串不能为null也不能为空（一般只用在字符串）V.NULL:对象、集合、数组、字符串、包装类必须为nullV.NOTEMPTY:集合、数组不能为null，元素个数不能为0；字符串不能为null也不能为空;对象不能为nullV.URL:参数必须是一个URLV.EMAIL:参数必须是email格式V.PAST:日期必须在当前日期的过去V.FUTURE:日期必须在当前日期的未来正则表达式:例如11位手机号-^[1]\\d{10}$msgs:数据校验消息，和valids规则一一对应，如果msgs没有设置，会有默认错误提示range:数值范围限制判断，包括整数和小数#例如: #range="1-10^取值范围是1到10":"-"左边代表最小值，右边代表最大值，"^"右边代表提示消息。#range="*-10^取值不能大10":"-"左边如果是"*"号代表不限制最小值，右边代表最大值，"^"右边代表提示消息。#range="1-*":"-"左边代表最小值，右边如果是"*"号代表不限制最大值，如果后面没有"^"会有默认错误提示。size:集合、数组大小限制判断#用法和range一样length:字符串长度限制判断#用法和range一样

7.3 ValidDataException异常对象

7.3.1 说明

如果接口有参数数据校验不通过，Lkadoc会抛出一个ValidDataException异常，可通过该异常对象的getMessage()方法获取所有没有校验通过的错误提示信息字符串，多个会用“;”隔开。除此之外ValidDataException异常对象还可以通过getErrors()方法获取所有没有校验通过的错误信息的Map集合，key对应的是参数名称，value对应的是校验错误信息。大家可以很方便的定制化返回错误结果信息。

7.3.2 在全局异常中处理校验信息

packagecom.lkad;
importjava.util.HashMap;
importjava.util.Map;
importjava.util.Set;
importorg.springframework.web.bind.annotation.ControllerAdvice;
importorg.springframework.web.bind.annotation.ExceptionHandler;
importorg.springframework.web.bind.annotation.ResponseBody;
importcom.lk.api.exception.ValidDataException;
/** * 注意事项: * 1.全局异常的包位置必须要在抛出异常接口位置的上层或同层 * 2.全局异常的包位置必须要在启动类的下层或同层 */@ControllerAdvicepublicclassExceptionController {
/** * 定义要捕获的异常可以多个 @ExceptionHandler({}) * 下面只是一个演示代码，仅供参考！ * @return 响应结果 */@ExceptionHandler(ValidDataException.class)
@ResponseBodypublicMap<String,Object> validExceptionHandler(ValidDataExceptione) {
Map<String, String> errors = e.getErrors();
Set<String> keySet = errors.keySet();
for (Stringkey : keySet) {
Stringvalue = errors.get(key);
System.out.println(key+"-"+value);
}
Map<String,Object> map = newHashMap<String, Object>();
map.put("code",500);
map.put("message",e.getMessage());
returnmap;
}
}

7.4 案例演示

7.4.1 NOTNULL

1.支持对集合、数组、字符串、对象、包装类请求参数判断不能为null,否则抛出ValidDataException
2.字符串可以为空串
3.不支持path参数校验，因为如果path参数为null的话，会改变url地址
4.如果没有设置msgs校验错误提示信息会有默认提示-xxx值不能为NULL。(xxx代表参数名称)

测试代码

packagecom.lkad.api;
importjava.util.HashMap;
importjava.util.Map;
importorg.springframework.web.bind.annotation.PostMapping;
importorg.springframework.web.bind.annotation.RequestMapping;
importorg.springframework.web.bind.annotation.RestController;
importcom.lk.api.annotation.*;
importcom.lk.api.constant.V;
@LKAType("数据校验功能演示")
@RestController@RequestMapping("valids")
publicclassValidsController {
/**没有加msgs校验提示信息，Lkadoc会有默认提示信息*/@LKAMethod("NOTNULL")
@LKAParam(names= {"name","pwd","age"},values= {"用户名","密码","年龄"},valids= {V.NOTNULL,V.NOTNULL,V.NOTNULL})
@PostMapping("testNotNull")
publicMap<String,Object> testNotNull(Stringname,Stringemail,Integerage) {
Map<String,Object> map = newHashMap<String, Object>();
map.put("code",200);
map.put("msg","登录成功");
returnmap;
}
}

效果图

全局异常在控制台打印的信息

7.4.2 NOTBLANK

1.支持对字符串参数判断不能为null也不能为空串,否则抛出ValidDataException
2.不支持path参数校验，因为如果path参数为null的话，会改变url地址
3.如果没有设置msgs校验错误提示信息会有默认提示-xxx值不能为空。(xxx代表参数名称)

测试代码

/**在ValidsController类增加如下测试接口*/@LKAMethod("NOTBLANK")
@LKAParams({
/** 注意： 1.name设置了msgs提示信息，默认提示信息会被msgs信息覆盖掉 2.@LKAParam只描述一个参数的话，支持设置多个校验规则 */@LKAParam(name="name",value="用户名",valids= {V.NOTBLANK},msgs= {"用户名不能为空"}),
@LKAParam(name="pwd",value="密码",valids= {V.NOTBLANK}),
@LKAParam(name="age",value="年龄",dataType=Integer.class,valids= {V.NOTNULL})
})
@PostMapping("testNotBlank")
publicMap<String,Object> testNotBlank(Stringname,Stringemail,Integerage) {
Map<String,Object> map = newHashMap<String, Object>();
map.put("code",200);
map.put("msg","登录成功");
returnmap;
}

效果图

全局异常在控制台打印的信息

7.4.3 NULL

1.支持对集合、数组、字符串、对象、包装类请求参数判断只能为null。否则抛出ValidDataException
2.如果没有设置msgs校验错误提示信息会有默认提示-xxx值只能为NULL。(xxx代表参数名称)

测试代码

/**在ValidsController类增加如下测试接口*/@LKAMethod("NULL")
@LKAParam(name= "age",value= "年龄",dataType=Integer.class,valids= {V.NULL})
@PostMapping("testNull")
publicMap<String,Object> testNull(Integerage) {
Map<String,Object> map = newHashMap<String, Object>();
map.put("code",200);
map.put("msg","操作成功");
returnmap;
}

效果图

全局异常在控制台打印的信息

7.4.4 NOTEMPTY

1.支持对集合、数组判断不能为null，元素个数不能为0；字符串不能为null也不能为空;对象、包装类不能为null。否则抛出ValidDataException
2.如果没有设置msgs校验错误提示信息会有默认提示-xxx值不能为NULL/空。(xxx代表参数名称)

测试代码

@LKAModelpublicclassUser {
@LKAProperty(value="用户ID",hidden=true)//hidden设置成true，该不会在UI界面展示privateIntegerid;
@LKAProperty(value="用户名称^张三",valids= {V.NOTEMPTY})
privateStringname;
@LKAProperty(value="年龄^20",valids= {V.NOTEMPTY})
privateStringage;
@LKAProperty(value="角色对象",type=Role.class,valids= {V.NOTEMPTY})
privateRolerole;
@LKAProperty(value="用户爱好^运动",isArray=true,valids= {V.NOTEMPTY})
privateString[] likes;
@LKAProperty(value="地址信息",isArray=true,type=Address.class,valids= {V.NOTEMPTY})
privateList<Address> addresses;
....get/set方法....
}
/**在ValidsController类增加如下测试接口*/@LKAMethod(value="NOTEMPTY",contentType=ContentType.JSON)
@PostMapping("testNotEmpty")
publicMap<String,Object> testNotEmpty(@RequestBodyUseruser) {
Map<String,Object> map = newHashMap<String, Object>();
map.put("code",200);
map.put("msg","操作成功");
returnmap;
}

效果图

7.4.5 URL、EMAIL、PAST、FUTURE

1.URL:参数必须是一个URL，可以为null。否则抛出ValidDataException
2.EMAIL:参数必须是email格式，可以为null。否则抛出ValidDataException
3.PAST:日期必须在当前日期的过去，可以为null。否则抛出ValidDataException
4.FUTURE:日期必须在当前日期的未来，可以为null。否则抛出ValidDataException

测试代码

@LKAModelpublicclassEmp {
@LKAProperty(value="生日",valids= {V.PAST,V.NOTNULL},msgs= {"生日必须在过去","请填写生日信息"})
privateDatebirthday;
@LKAProperty(value="退休日期",valids= {V.FUTURE,V.NOTNULL})
privateDateretirementDate;
@LKAProperty(value="个人主页",valids= {V.URL})
privateStringurl;
@LKAProperty(value="邮箱",valids= {V.EMAIL})
privateStringemail;
....get/set方法....
}
/**在ValidsController类增加如下测试接口*/@LKAMethod(value="URL、EMAIL、PAST、FUTURE",contentType=ContentType.JSON)
@PostMapping("testUEPF")
publicMap<String,Object> testUEPF(@RequestBodyEmpemp) {
Map<String,Object> map = newHashMap<String, Object>();
map.put("code",200);
map.put("msg","操作成功");
returnmap;
}

效果图

7.4.6 正则表达式

Lkadoc还支持正则表达式的匹配，参数值可以为null。正则没有匹配上则抛出ValidDataException

测试代码

@LKAModelpublicclassEmp {
@LKAProperty(value="生日",valids= {V.PAST,V.NOTNULL},msgs= {"生日必须在过去","请填写生日信息"})
privateDatebirthday;
@LKAProperty(value="退休日期",valids= {V.FUTURE,V.NOTNULL})
privateDateretirementDate;
@LKAProperty(value="个人主页",valids= {V.URL})
privateStringurl;
@LKAProperty(value="邮箱",valids= {V.EMAIL})
privateStringemail;
@LKAProperty(value="手机号",valids= {"^[1]\\d{10}$",V.NOTNULL},msgs= {"手机号必须是11位","手机号不能为null"})
privateStringmobile;
....get/set方法....
}
@LKAMethod(value="URL、EMAIL、PAST、FUTURE",contentType=ContentType.JSON)
@PostMapping("testUEPF")
publicMap<String,Object> testUEPF(@RequestBodyEmpemp) {
Map<String,Object> map = newHashMap<String, Object>();
map.put("code",200);
map.put("msg","操作成功");
returnmap;
}

效果图

7.4.7 range、size、length

range、size、length是单独的属性，可以和valids规则同时存在,参数可以为null
range:数值范围限制判断，包括整数和小数
#例如: #range="1-10^取值范围是1到10":"-"左边代表最小值，右边代表最大值，"^"右边代表提示消息。
#range="*-10^取值不能大10":"-"左边如果是"*"号代表不限制最小值，右边代表最大值，"^"右边代表提示消息。
#range="1-*":"-"左边代表最小值，右边如果是"*"号代表不限制最大值，如果后面没有"^"会有默认错误提示。
size:集合、数组大小限制判断
#用法和range一样
length:字符串长度限制判断
#用法和range一样

测试代码

@LKAModelpublicclassEmp {
@LKAProperty(value="年龄",range="1-130^年龄取值必须在1到130之间")
privateIntegerage;
@LKAProperty(value="爱好",size="2-*^至少填写2个爱好")
privateString[] like;
@LKAProperty(value="姓名",length="2-6")
privateStringname;
....get/set方法....
}
@LKAMethod(value="range、size、length",contentType=ContentType.JSON)
@PostMapping("testRSL")
publicMap<String,Object> testRSL(@RequestBodyEmpemp) {
Map<String,Object> map = newHashMap<String, Object>();
map.put("code",200);
map.put("msg","登录成功");
returnmap;
}

效果图

全局异常在控制台打印的信息

7.4.8 参数分组

数据校验也支持参数分组，如要入参是一个对象，且对象设置了分组，那么只有组内属性才会进行数据校验。具体可参考高级应用里面的对象参数分组。

@LKAModelpublicclassEmp {
@LKAProperty(value="年龄",range="1-130^年龄取值必须在1到130之间",groups= {"testRSL"})
privateIntegerage;
@LKAProperty(value="爱好",size="2-*^至少填写2个爱好")
privateString[] like;
@LKAProperty(value="姓名",length="2-6")
privateStringname;
....get/set方法....
}
@LKAMethod(value="range、size、length",contentType=ContentType.JSON)
@PostMapping("testRSL")
publicMap<String,Object> testRSL(@RequestBody@LKAGroup("testRSL") Empemp) {
Map<String,Object> map = newHashMap<String, Object>();
map.put("code",200);
map.put("msg","登录成功");
returnmap;
}

效果图

项目开源地址：https://github.com/liukaitydn/LKADocument

如果大家学得好用，记得给星哦

Name		Name	Last commit message	Last commit date
Latest commit History 74 Commits
.recommenders/caches		.recommenders/caches
LKADocument		LKADocument
.gitignore		.gitignore
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

1. 前言

2. 介绍

版本更新说明：

lkadoc 1.2.4于2020年9月24日发布：

lkadoc 1.2.3于2020年9月15日发布：

lkadoc 1.2.2 修复1.2.1不能导出pdf和md的功能

lkadoc 1.2.1 于2020年8月5日发布(有bug，导出有问题，请使用1.2.2版)：

3. 准备工作

3.1 在SpringBoot项目中引入两个jar包

3.2 在SpringBoot项目启动类上加上@LKADocument注解

3.3 在application.yml文件中添加如下配置

3.4 准备测试代码

3.5 打开浏览器，输入地址http://127.0.0.1:8080/lkadoc.html 查看效果如下：

4. 基础入门

4.1 LKAType注解

4.2 LKAMethod注解

4.2.1 LKAType和LKAMethod演示代码

4.3 运用版本号快速定位新接口

4.3.1 案例：

4.4 LKAParam和LKAParams注解

4.4.1 常用属性解析

4.4.2 测试代码

4.5 调试API功能

4.5.1 测试API请求

4.5.2 压力测试

4.6 全局token锁定

4.7 数组传参

4.7.1 注意事项

4.7.2 测试代码

4.8 文件上传

4.8.1 注意事项

4.8.2 测试代码

4.9 文件下载

4.9.1 注意事项

4.9.2 测试代码

5. 高级应用

5.1 LKAModel注解

5.2 LKAProperty注解

5.3 基本对象入参

5.3.1 注意事项

5.3.2 测试代码

5.4 复杂的对象入参

5.4.1 注意事项

5.4.2 测试代码

5.5 对象参数分组

5.5.1 注意事项

5.5.2 测试代码

5.6 响应参数的基本用法

5.6.1 LKARespose/LKAResposes注解

5.6.2 简单Map集合出参

5.6.3 对象出参

5.7 复杂的Map结构出参

5.7.1 说明

5.7.2 测试代码

5.7.3 超过3层嵌套结构用法技巧

5.7.4 测试代码

5.8 复杂的对象结构出参

5.8.1 准备一个响应封装对象

5.8.2 准备一个测试接口

5.9 响应参数对象属性分组

5.9.1 准备一个对象属性过滤器

5.9.2 给对象属性分组

5.9.3 测试代码：

6. 辅助功能

6.1 自定义接口或属性标签

6.2 导出PDF或MarkDown文档

6.3 多项目聚合

6.4 UI风格切换

7. 数据校验

7.1 准备工作

7.2 规则说明

7.3 ValidDataException异常对象

7.3.1 说明

7.3.2 在全局异常中处理校验信息

7.4 案例演示

7.4.1 NOTNULL