告別手寫接口文檔時代，比Swagger功能更強大的LKADocument接口文檔管理框架誕生了！

更詳細的更全面的教程請觀看做者親自錄製的視頻教程，地址：

https://edu.51cto.com/sd/9cb7fLKADocument視頻教程

1、介紹

在先後端分離，分工更加明細化的今天，爲了減小前端和後臺開發人員的溝通成本，可以讓他們作到並行開發，同時也能保證前端和後端開發人員所看到的接口文檔的一致性，即時性，以此來大大提升工做效率。因此出現了一些很是優秀的接口管理工具，具備表明性的像Swagger，由於它可以經過註解或yml和JSON描述文件來自動生成接口文檔。可是我以爲它不論是在配置過程仍是正常使用過程都不是特別好用，特別是對對象參數和複雜的參數註釋很不友好，對前端開發人員更不友好。
因此，LKADocument誕生了！LKADocument它也是一款基於Spring Web可以全自動生成接口文檔管理的JAVA後臺框架，沒錯！確實和swagger很像，但比swagger更增強大和智能，整體來講，要比swagger配置更簡單，使用起來更方便，在參數註釋和UI展現這一塊功能更增強大，任何複雜的請求參數和響應參數都可以用註解描述出來，一樣也支持接口在線調試，支持rest風格的接口。UI操做界面更符合中國程序員的口味，同時對前端和後端開發人員更加友好，特別是後端開發人員。先來幾張圖片你們感覺一下強大的功能：

2、添加LKADocument插件到SpringBoot項目

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瀏覽器打開顯示有問題

3、快速入門：

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屬性分組

案例：略

4、LKADocument的高級應用

1.數組請求入參功能

2.複雜的請求、響應字段功能演示

3.文件上傳功能

4.修改接口參數備註信息添加和刪除功能

5.其它功能

更詳細的更全面的教程請觀看做者親自錄製的視頻教程，地址：

https://edu.51cto.com/sd/9cb7fLKADocument視頻教程