告别手写接口文档时代，比Swagger功能更强大的LKADocument接口文档管理框架诞生了！

发布时间：2020-04-17 23:15:15 作者：wx5cbdbfeb82e55
来源：网络阅读：3080

更详细的更全面的教程请观看作者亲自录制的视频教程，地址：

https://edu.51cto.com/sd/9cb7fLKADocument视频教程

一、介绍

在前后端分离，分工更加明细化的今天，为了减少前端和后台开发人员的沟通成本，能够让他们做到并行开发，同时也能保证前端和后端开发人员所看到的接口文档的一致性，即时性，以此来大大提高工作效率。所以出现了一些非常优秀的接口管理工具，具有代表性的像Swagger，因为它能够通过注解或yml和JSON描述文件来自动生成接口文档。但是我觉得它不管是在配置过程还是正常使用过程都不是特别好用，特别是对对象参数和复杂的参数注释很不友好，对前端开发人员更不友好。
所以，LKADocument诞生了！LKADocument它也是一款基于Spring Web能够全自动生成接口文档管理的JAVA后台框架，没错！确实和swagger很像，但比swagger更加强大和智能，总体来说，要比swagger配置更简单，使用起来更方便，在参数注释和UI展示这一块功能更加强大，任何复杂的请求参数和响应参数都能够用注解描述出来，同样也支持接口在线调试，支持rest风格的接口。UI操作界面更符合中国程序员的口味，同时对前端和后端开发人员更加友好，特别是后端开发人员。先来几张图片大家感受一下强大的功能：

告别手写接口文档时代，比Swagger功能更强大的LKADocument接口文档管理框架诞生了！

二、添加LKADocument插件到SpringBoot项目

1.在项目根路径创建一个lib文件夹，把LKADocument对应的jar复制进去(目前还没有放到maven中央或镜像仓库，故采用本地引入的方式)：
告别手写接口文档时代，比Swagger功能更强大的LKADocument接口文档管理框架诞生了！

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，如果配置没有问题可以看下如下界面：

告别手写接口文档时代，比Swagger功能更强大的LKADocument接口文档管理框架诞生了！

注意：目前用火狐和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";
}

效果图：

树版:

告别手写接口文档时代，比Swagger功能更强大的LKADocument接口文档管理框架诞生了！

横版:

告别手写接口文档时代，比Swagger功能更强大的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;
    }

效果图(只展示树版)：

告别手写接口文档时代，比Swagger功能更强大的LKADocument接口文档管理框架诞生了！

案例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;
}

效果图(只展示树版)：

告别手写接口文档时代，比Swagger功能更强大的LKADocument接口文档管理框架诞生了！

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;
}

效果图(横版样式)：

告别手写接口文档时代，比Swagger功能更强大的LKADocument接口文档管理框架诞生了！

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;
}

效果图，我们可以看到，和上一个案例效果是一样的 (横版样式)：

告别手写接口文档时代，比Swagger功能更强大的LKADocument接口文档管理框架诞生了！

案例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;
    }

效果图：

告别手写接口文档时代，比Swagger功能更强大的LKADocument接口文档管理框架诞生了！

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视频教程

告别手写接口文档时代，比Swagger功能更强大的LKADocument接口文档管理框架诞生了！

一、介绍

二、添加LKADocument插件到SpringBoot项目

三、快速入门：

四、LKADocument的高级应用

相关阅读