Farewell to the era of handwritten interface documents, the more powerful LKADocument interface document management framework than Swagger was born!

For more detailed and comprehensive tutorials, please watch the video tutorials recorded by the author. Address:

https://edu.51cto.com/sd/9cb7fLKADocument video tutorial

I. Introduction

Today, with the separation of front and back ends and more detailed division of labor, in order to reduce the communication cost of front-end and back-end developers, they can develop in parallel, and also ensure the consistency and instantaneity of interface documents seen by front-end and back-end developers, so as to greatly improve the work efficiency. So there are some excellent interface management tools, such as Swagger, which can generate interface documents automatically through annotations or yml and JSON description files. But I don't think it's particularly easy to use in the configuration process or normal use process, especially for object parameters and complex Parameter annotation, and for front-end developers.
So, LKADocument was born! LKADocument is also a JAVA background framework based on Spring Web that can automatically generate interface document management. That's right! It's really similar to swagger, but it's more powerful and intelligent than swagger. In general, it's simpler than swagger configuration and more convenient to use. It's more powerful in Parameter annotation and UI display. Any complex request parameter and response parameter can be described by annotation. It also supports online debugging of interface and rest style interface. UI operation interface is more in line with the taste of Chinese programmers, and more friendly to front-end and back-end developers, especially back-end developers. Let's take a few pictures first. Let's feel the powerful function:









2, Add LKADocument plug-in to SpringBoot project

1. Create a lib folder in the root path of the project, and copy the jar corresponding to LKADocument (currently it has not been placed in the maven central or image warehouse, so it is imported locally):

2. Add dependency import in 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. Add configuration in application.yml:

lkad:
  basePackages: com.xb #Specifies the package path to scan. Multiple package paths can be separated by ","
  projectName: lkad Test items #entry name
  description: Be based on LKADocument Interface documents automatically generated by tools #Project description
  enabled: true #Enable lkad to automatically generate interface documents. The default is true

4. Add @ LKADocument annotation to the project startup class

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. Open the website http://127.0.0.1:8088/lkadocb.html, if there is no problem in the configuration, you can see the following interface:

Note: at present, Firefox and Chrome can be opened normally. There is a problem in the display of IE

3, Quick start:

1.@LKAType note:

Note: this annotation is used on the class. In order to be compatible with Swagger, you can also use @ Api annotation instead

Function: used to identify the classes that need LKADocument scanning. This class usually contains API s that need to generate interface documents automatically, such as common Controller classes

Properties:

value: class description (if annotated with @ Api, this property is named tags)
Description: class description (not required)

Case study:

/**
Short version: @ LKAType("test class")
Full version: @ LKAType(value = "test class", description = "this class is used to test LKADocument")
*/
@LKAType(value="Test class",description="This class is used to test LKADocument")
@RestController
public class TestController {....}

2.@LKAMethod note:

Note: this annotation is used on methods. It will take effect only when the @ LKAType annotation is added to the class of the method. In order to be compatible with Swagger, the @ ApiOperation annotation can also be used instead

Function: used to identify the methods that need LKADocument scanning. The scanned methods will automatically generate interface documents

Properties:

value: method description
 Description: method description (if annotated with @ ApiOperation, this property is named notes)
Version: version number, default value is "none"
contentType:contentType type, the default value is "application/x-www-form-urlencoded", and the value can also be "application/json"

Case study:

/**
Short version: @ LKAMethod("hello test")
Full version: @ LKAMethod(value="hello test", description = "test @ LKAMethod method", version = "v1.0", contenttype = lkad. X ﹣ www ﹣ form ﹣ rulencoded)
*/
@LKAMethod(value="hello test",description="Test interface",version="v1.0",contentType="application/x-www-form-urlencoded")
@GetMapping("hello")
public String hello() {
    return "hello LKADocument";
}

Design sketch:

Tree Edition:

Horizontal plate:

3.@LKAParam annotation and @ lkaparms:

Note: this annotation is used on methods. Only when the method is annotated with @ LKAMethod will it take effect. In order to be compatible with Swagger, the @ ApiImplicitParam and @ ApiImplicitParam annotations can be used instead

Function: used to describe the input parameter field of the interface

Properties:

value: field description
 Name: field name
 Description: field description
 dataType: field type, default value is String
 Required: required or not. The value is true or false. The default value is true
 paramType: input parameter method, value query(params input parameter), header (request header input parameter), path (request address input parameter), default value is query
 testData: test data
 isArray: whether it is an array input parameter. The value is true or false. The default value is false
 Type: object input parameter, value object type. If the input parameter is an object, all the above attributes are invalid except name attribute
 Group: group of object attributes, used in conjunction with the type attribute, takes the group name, which can be used for grouping when the incoming parameter does not need to transfer all the attributes of the object

Case 1:

//params entry
@LKAMethod(value="according to ID Get user information",version="v1.0")
//Short version: @ LKAParam(value = "user id",name="id")
@LKAParam(value="user id",name="id",description="user 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("Xiao Bai");
    user.setEmail("123@qq.com");
    user.setAge(22);
    return user;
}
//Or path
@LKAMethod(value="according to ID Get user information",version="v1.0")
    //Short version: @ LKAParam(value = "user id",name="id")
    @LKAParam(value="user id",name="id",description="user 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("Xiao Bai");
        user.setEmail("123@qq.com");
        user.setAge(22);
        return user;
    }

Rendering (tree version only):

Case 2:

@LKAMethod(value="New user information",version="v1.0")
@LKAParams({
    @LKAParam(value="Sign in token",name="x_token",description="Token returned by the server after the user logs in successfully",paramType=Lkad.HEADER,testData="lekwnddfekwes"),
    @LKAParam(value="User name",name="name",description="Up to 5 Chinese characters",paramType=Lkad.QUERY,testData="Xiao Ming"),
    @LKAParam(value="User mail box",name="email",required=false,paramType=Lkad.QUERY,testData="321@qq.com"),
    @LKAParam(value="User age",name="age",description="18-30 Between",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", "Save successfully");
    map.put("result", x_token);
    return map;
}

Rendering (tree version only):

4.@LKAModel notes

Note: this annotation is used on objects. In order to be compatible with Swagger, you can also use @ ApiMode annotation instead

Function: used to describe model object

Properties:

value: object description
 Description: object description

5. @ lkpropertynotes

Note: this annotation is used on object properties. In order to be compatible with Swagger, the @ ApiModelProperty annotation can also be used instead

Function: used to describe the properties of model object

Properties:

value: attribute description
 Description: attribute description
 dataType: field type, default value is String
 Required: required or not. The value is true or false. The default value is true
 paramType: input parameter method, value query(params input parameter), header (request header input parameter), path (request address input parameter), default value is query
 testData: test data
 isArray: whether it is an array input parameter. The value is true or false. The default value is false
 Type: nested object input parameter, value object type. If the input parameter is an object, all the above attributes are invalid except name attribute
 Groups: groups of object attributes. Multiple groups are separated by ","

Case study:

/*User object*/
package com.xb.domain;

import com.lk.api.annotation.LKAModel;
import com.lk.api.annotation.LKAProperty;

@LKAModel("User object")
public class User {
    @LKAProperty(value="user id",testData="3")
    private Integer id;
    @LKAProperty(value="User name",groups= {"add"},testData="Xiaohong")
    private String name;
    @LKAProperty(value="User mail box",groups= {"add"},testData="456@qq.com")
    private String email;
    //The group attribute add is followed by - N, which means that this parameter is not required. If - n is not added, it is required
    @LKAProperty(value="User age",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;
    }
}

/*Test interface*/
@LKAMethod(value="New user information 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", "Save successfully");
    Map<String,Object> map2 = new HashMap<>();
    map2.put("user", user);
    map2.put("x_token", x_token);
    map.put("result",map2);
    return map;
}

Renderings (horizontal style):

6. @ lkager note:

Note: this annotation is used on the method input object

Function: used to specify the attribute grouping of the parameter object. LKADocument can automatically scan the object with @ LKAModel annotation, and omit @ LKAParam annotation on the method to describe the parameter object. At this time, if you want to specify the grouping, you can use @ Group annotation

Case study:

@LKAMethod(value="New user information 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", "Save successfully");
    Map<String,Object> map2 = new HashMap<>();
    map2.put("user", user);
    map2.put("x_token", x_token);
    map.put("result",map2);
    return map;
}

We can see that the effect of the renderings is the same as that of the previous case (horizontal style):

Case 2, complex object input:

/*Address object*/
package com.xb.domain;

import com.lk.api.annotation.LKAModel;
import com.lk.api.annotation.LKAProperty;

@LKAModel("User address object")
public class Address {

    @LKAProperty("address ID")
    private Integer id;
    @LKAProperty(value="Province",groups= {"add2"},testData="Hunan")
    private String province;
    @LKAProperty(value="City",groups= {"add2"},testData="city in Hunan")
    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;
    }
}

/*Role object*/
package com.xb.domain;

import com.lk.api.annotation.LKAModel;
import com.lk.api.annotation.LKAProperty;

@LKAModel("Role object")
public class Role {
    @LKAProperty(value = "role ID")
    private Integer id;
    @LKAProperty(value = "Role name",groups={"add2"},testData="Administrators")
    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 object*/
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("User object")
public class User {
    @LKAProperty(value="user id",testData="3")
    private Integer id;

    @LKAProperty(value="User name",groups= {"add","add2"},testData="Xiaohong")
    private String name;

    @LKAProperty(value="User mail box",groups= {"add","add2"},testData="456@qq.com")
    private String email;

    @LKAProperty(value="User age",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;
    }
}

/*Test interface*/
@LKAMethod(value="New user information 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", "Save successfully");
        Map<String,Object> map2 = new HashMap<>();
        map2.put("user", user);
        map2.put("x_token", x_token);
        map.put("result",map2);
        return map;
    }

Design sketch:

7.@LKAResposes and @ LKARespose

Note: this annotation is used on the method. It will take effect only when the @ LKAMethod annotation is added to the class of the method

Function: used to describe the response field of the interface

Properties:

value: field description
 Name: parameter name
 Description: parameter description
 dataType: parameter type default "String"
isArray: whether it is an array input parameter. The value is true or false. The default value is false
 parentName: parent field name
 Type: outgoing parameter model object type
 group: outgoing parameter model attribute grouping

Case: slightly

4, Advanced application of LKADocument

1. Array request parameter function

2. Function demonstration of complex request and response fields

3. File upload function

4. Modify the function of adding and deleting interface parameter remarks

5. Other functions

For more detailed and comprehensive tutorials, please watch the video tutorials recorded by the author. Address:

https://edu.51cto.com/sd/9cb7fLKADocument video tutorial

Postscript: originally this set of video was intended to be free, but I found that as a 30-year-old programmer, the deposit is not more than 5 digits. Conditions do not allow me to free ah, the reality is that I am just a programmer with a trace of sadness. You should treat me to a cup of coffee. In the end, I hope you can support me a lot. Your support is the driving force for the struggle!

Tags: Java Attribute JSON snapshot

Posted on Thu, 13 Feb 2020 00:42:05 -0800 by dethknite