<!--Lkadoc пакет-->
<dependency>
    <groupId>com.github.liukaitydn</groupId>
    <artifactId>lkadoc-api</artifactId>
    <version>2.0.0</version>
</dependency>
<dependency>
    <groupId>com.github.liukaitydn</groupId>
    <artifactId>lkadoc-annotations</artifactId>
    <version>2.0.0</version>
</dependency>

@LKADocument(basePackages="com.lkad.api")
@SpringBootApplication
public class LkadocDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(LkadocDemoApplication.class, args);
    }
}

@LKAType(value="модуль регистрации и входа пользователя")
@RestController
@RequestMapping("user")
public class LKADemoController {
 
        @LKAMethod(value="регистрация")
        //@LKAParam(names= {"name","pwd"},values= {"имя пользователя","пароль"})
        @LKARespose(names= {"code","msg"},values= {"код состояния","сообщение"})
        @PostMapping("login")
        public Map<String,Object> login(@LKAParam(name="name",value="имя пользователя")String name, @LKAParam(name="pwd",value="пароль")String pwd) {
            Map<String,Object> map = new HashMap<>();
            map.put("code",200);
            map.put("msg","успешная регистрация,"+name+" добро пожаловать в систему");
            return map;
        }
}

# Используется для описания информации о классе. Общие свойства:

value: назначение класса (обязательно)
description: описание класса (необязательно)
hidden: скрывает ли класс информацию в пользовательском интерфейсе. По умолчанию — false. Если установлено значение true, вся информация об интерфейсах в этом классе также будет скрыта (необязательно).
order: сортировка. Чем меньше значение, тем выше в списке (необязательно).

# Используется для описания информации об интерфейсе. Общие свойства:

value: цель интерфейса (обязательно).
description: описание интерфейса (необязательно).
contentType: тип заголовка ContentType по умолчанию — application/x-www-form-urlencoded (необязательно).
author: автор (необязательно).
createTime: время создания интерфейса (необязательно).
updateTime: время обновления интерфейса (необязательно).
hidden: скрывается ли интерфейс в пользовательском интерфейсе. Значение по умолчанию — false (необязательно).
version: номер версии интерфейса. Если номера версий интерфейсов совпадают, в пользовательском интерфейсе они будут отмечены как новые (необязательно).
download: требуется ли загрузка. Если интерфейс связан с загрузкой файла, необходимо установить значение true. Значение по умолчанию — false (необязательно).
token: требуется ли проверка токена. Только указывает на необходимость проверки токена, не влияет на нормальную работу. Значение по умолчанию — true (необязательно).
order: сортировка. Чем меньше число, тем выше оно в списке (необязательно).
directory: указывает на родительский каталог (здесь каталог относится к значению свойства value аннотации @LKAType. Родительский каталог должен существовать, иначе он не будет отображаться в документации по интерфейсу. Значение по умолчанию — текущий класс).

# Используется для описания информации о параметрах запроса. С версии 2.0.0 аннотацию @LKAParam можно применять не только к методам, но и к параметрам. Добавление s к свойству делает его множественным. Но обратите внимание, что при настройке свойств с s и без s одновременно можно выбрать только одно. Рекомендуется использовать s для всех параметров, независимо от того, один это параметр или несколько. Использование s более гибкое и интеллектуальное. Общие свойства:

name/names: имя параметра (обязательно) (используется name для установки имени параметра. Необходимо использовать; используется names для установки имени параметра. Можно опустить. Однако для этого требуется JDK версии 1.8 или выше, а во время компиляции необходимо добавить параметр запуска –parameters. Lkadoc автоматически получит имена параметров. В настоящее время тестирование JDK11 без параметра –parameters также может распознавать имена параметров, в противном случае необходимо).
value/values: назначение параметра (обязательно).
description/descriptions: описание параметра (необязательно).
dataType/dataTypes: тип данных (необязательно) (используйте dataType для настройки значения по умолчанию String.class. Используйте dataTypes для автоматического получения типа данных параметра. Опустите настройку, если это необходимо, но обратите внимание на порядок параметров).
required/requireds: обязательный параметр. Значение по умолчанию — true (необязательно) (более простой способ использования — добавить -n после значения свойства name или добавить n~ перед значением свойства value, чтобы указать, что параметр не является обязательным. Три способа эквивалентны).
paramType/paramTypes: позиция параметра, query, header, path (необязательно) (настройка paramType по умолчанию равна query. Настройка paramTypes позволяет Lkadoc автоматически получать позицию параметра на основе аннотаций @PathVariable и @RequestHeader. Опустите настройку, если она не нужна).
isArray/isArrays: является ли параметр коллекцией или массивом. Значение по умолчанию — false (необязательно).
testData/testDatas: тестовые данные (необязательно) (проще использовать значение после символа ^ для добавления тестовых данных).
type: тип входящего объекта (необязательно) (когда запрос параметра является объектом, используйте type для указания. Обычно настройка не требуется, и она может быть автоматически распознана).
group: используется вместе с типом для группировки объектов параметров. Можно фильтровать ненужные параметры (необязательно).

# Используется для описания информации о модели. Общие свойства:
value: роль атрибута (необязательно).
description: описание атрибута (необязательно).

# Используется для описания атрибутов модели. Свойства аналогичны свойствам аннотации @LKAParam. Здесь не приводится пример.
value: роль атрибута (обязательно).
description: описание атрибута (необязательно).
hidden: скрывать ли атрибут в пользовательском интерфейсе. Значение по умолчанию — false (необязательно).
testData: тестовые данные (необязательно) (проще использовать значение после символа ^ для добавления тестовых данных).
required: является ли атрибут обязательным параметром. Значение по умолчанию — true (необязательно) (проще использовать n~ перед значением, чтобы указать, что атрибут не является обязательным).
isArray: является ли атрибут массивом или коллекцией. Не требуется настройка, можно автоматически распознать (необязательно).
type: когда атрибут является типом объекта, можно использовать type для указания, настройка не требуется, можно автоматически распознать (необязательно).
groups: используется для группировки параметров. Можно настроить несколько групп (необязательно) (при использовании required в группах настройка -n после имени группы указывает, что группа не является обязательной. Без настройки -n группа является обязательной).

...
``` **Аннотация @LKAGroup** — это аннотация-параметр, которая определяет, к какой группе параметров относится объект.

# Используется для описания информации о параметрах ответа, и его использование похоже на аннотацию @LKAParam. Здесь не приводятся примеры.
# Общие атрибуты:
name/names: имя параметра, можно выбрать один из двух атрибутов: name или names [обязательно]
value/values: назначение параметра [обязательно]
description/descriptions: описание параметра [обязательно]
dataType/dataTypes: тип данных параметра, если dataTypes не установлен, он может автоматически определить тип [необязательно]
isArray/isArrays: является ли это коллекцией или массивом, по умолчанию false [необязательно]
type: тип объекта параметра, можно автоматически определить, выбрав один из атрибутов type или name/names [необязательно]
group: используется вместе с типом, чтобы разделить параметры на группы, можно фильтровать ненужные параметры [необязательно]
# Родительские параметры:
parentName: имя родительского параметра [необязательно]
parentValue: назначение родительского параметра [необязательно]
parentDescription: описание родительского параметра [необязательно]
parentIsArray: родительский параметр является массивом или коллекцией [необязательно]
# Параметры дедушки:
grandpaName: имя параметра дедушки [необязательно]
grandpaValue: назначение параметра дедушки [необязательно]
grandpaDescription: описание параметра дедушки [необязательно]
grandpaIsArray: параметр дедушки является массивом или коллекцией [необязательно]

// Добавляем название проекта и описание
@LKADocument(basePackages="com.lkad.api",projectName = "Демонстрационный проект",description = "Используется для обучения Lkadoc")
@SpringBootApplication
public class LkadocDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(LkadocDemoApplication.class, args);
    }
}

// Обратите внимание: конфигурацию names={"name","pwd","email","age"} аннотации JDK8 и выше @LKAParam можно опустить
@LKAMethod(value="Регистрация пользователя",описание="Интерфейс регистрации приложения",версия="1.0",дата создания="2021-08-08",автор="LK")
@LKAParam(names={"имя","пароль","электронная почта","возраст"},значения= {"Имя^Чжан Фан","Пароль^123abc","Электронная почта^123@qq.com","Возраст^21"})
@PostMapping("reg")
public String reg(String name,String pwd,String email,Integer age) {
    if(name == null || "".equals(name) || pwd == null || "".equals(pwd)){
        return "Ошибка регистрации";
    }
    return "Регистрация прошла успешно";
}

@LKAMethod(значение="Параметры пути и заголовка")
@LKAParam(имена={"токен","имя","электронная почта"},значения= {"Токен^aaaa","Имя^Гуа Гуа","Электронная почта^123@qq.com"})
@PostMapping("getUser/{имя}/{электронная почта}")
public String getUser(@RequestHeader("токен") String token,
                      @PathVariable("имя") String name,
                      @PathVariable("электронная почта") String email) {

    return "Результат теста: токен="+token+",имя="+name+",электронная почта="+email;
}

// isArrays = {true,false} представляет первый параметр как массив, а второй параметр не как массив
@LKAMethod(значение="Массив параметров")
@LKAParam(имена={"идентификаторы","имя"},значения= {"Идентификатор пользователя^1001","Имя^Гуа Гуа"},isArrays = {true,false})
@PostMapping("массив")
public String array(Integer[] ids,String name) {

    return "Результат теста: идентификаторы="+ Arrays.toString(ids)+",имя="+name;
}

// ContentType.FORMDATA — константа со значением multipart/form-data
@LKAMethod(значение="Загрузка нескольких файлов",contentType=ContentType.FORMDATA)
@LKAParam(имена= "файлы",значения="Загружаемый файл",isArrays= true)
@PostMapping("fileUpload")
public String fileUpload(MultipartFile[] files) {
    String fileNames = "";
    if(files != null) {
        for (MultipartFile f : files) {
            if("".equals(fileNames)) {
                fileNames = f.getOriginalFilename();
            }else {
                fileNames = fileNames + ","+f.getOriginalFilename();
            }
        }
    }

    return "Успешная загрузка, имя файла:"+fileNames;
}

//@LKAMethod аннотация с параметром download=true указывает на то, что этот метод предназначен для скачивания файла. Перед тестированием этого метода необходимо подготовить файл test.txt на диске D.
@LKAMethod(value="Скачивание файла",download=true)
@PostMapping("fileDownload")
public void fileDownload(HttpServletResponse response) throws Exception {
    String path = "D:\\test.txt";
    File file = new File(path);
    String ext = file.getName().substring(file.getName().lastIndexOf(".") + 1).toUpperCase();
    InputStream fis = new BufferedInputStream(new FileInputStream(path));
    byte[] buffer = new byte[fis.available()];
    fis.read(buffer);
    fis.close();
    response.reset();
    response.addHeader("Content-Disposition", "attachment;filename=" + new String(file.getName().getBytes()));
    response.addHeader("Content-Length", "" + file.length());
    OutputStream toClient = new BufferedOutputStream(response.getOutputStream());
    response.setContentType("application/octet-stream");
    toClient.write(buffer);
    toClient.flush();
    toClient.close();
}

@LKAModel
public class Role {
    @LKAProperty(value = "Роль ID^101")
    private Integer id;
    @LKAProperty(value = "n~Роль^Название")
    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; }
}

@LKAMethod("Простой объект как входной параметр")
@GetMapping("getRole")
public Role getRole(Role role) {
    return role;
}

@LKAModel
public class Address {
    @LKAProperty(value="Адрес ID^1")
    private Integer id;
    @LKAProperty(value="n~Адресная информация^Шэньчжэнь, Лунхуа")
    private String info;

    public Integer getId() { return id; }
    public void setId(Integer id) { this.id = id; }
    public String getInfo() { return info; }
    public void setInfo(String info) { this.info = info; }
}

@LKAModel
public class User {
    @LKAProperty(value="Пользователь ID^1001")
    private Integer id;
    @LKAProperty(value="n~Имя пользователя^Чжан Сань")
    private String name;
    @LKAProperty(value="Возраст^20",description="Диапазон 0-120")
    private String age;
    @LKAProperty(value="Объект роли")
    private Role role;
    @LKAProperty(value="Любимое занятие пользователя^Спорт")
    private String[] likes;
    @LKAProperty(value="Информация об адресе")
    private List<Address> addresses;

    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 getAge() { return age; }
    public void setAge(String age) { this.age = age; }
    public Role getRole() { return role; }
    public void setRole(Role role) { this.role = role; }
    public String[] getLikes() { return likes; }
    public void setLikes(String[] likes) { this.likes = likes; }
    public List<Address> getAddresses() { return addresses; }
    public void setAddresses(List<Address> addresses) { this.addresses = addresses; }
}

/**
1. Для сложных объектов необходимо установить атрибут contentType аннотации @LKAMethod в значение "application/json".
2. Если contentType="application/json", то перед объектом параметра необходимо добавить аннотацию @RequestBody.
3. Если contentType="application/json", тип запроса интерфейса не может быть get.
*/
@LKAMethod(value="Сложный объект как входной параметр",contentType=ContentType.JSON)
@PostMapping("addUser")
public User addUser(@RequestBody User user) {
    return user;
}

HashMap<>();
data.put("total",10);
List<User> users = new ArrayList<>();
User user1 = new User();
user1.setName("张三");
User user2 = new User();
user2.setName("李四");
users.add(user1);
users.add(user2);
data.put("users",users);
map.put("result",data);
return map;
}

Через нажатие кнопки «Структурированное отображение параметров ответа» можно наглядно отобразить сложную структуру параметров ответа.

@LKAMethod(value="Использование структуры параметров ответа с более чем 3 уровнями вложенности")
@LKAResposes({
    @LKARespose(name="a",value="уровень 1"),
    @LKARespose(name="b",value="уровень 2",parentName="a"),
    @LKARespose(name="c",value="уровень 3",parentName="b"),
    @LKARespose(name="d",value="уровень 4",parentName="c")
})
@GetMapping("getMoreMap")
public Map<String,Object> getMoreMap(){
    Map<String,Object> mapa= new HashMap<>();
    Map<String,Object> mapb= new HashMap<>();
    Map<String,Object> mapc= new HashMap<>();
    Map<String,Object> mapd= new HashMap<>();
    mapa.put("a",mapb);
    mapb.put("b",mapc);
    mapc.put("c",mapd);
    mapd.put("d",1);
    return mapa;
}

Нажмите кнопку «Структурированное отображение параметров ответа», чтобы наглядно отобразить сложную структуру параметров ответа.

Отображение в формате JSON.

@LKAModel
public class ApiResult {
    @LKAProperty(value="Код состояния")
    private String code;
    @LKAProperty(value="Сообщение")
    private String msg;
    @LKAProperty(value="Данные ответа")
    private Map<String,Object> result = new HashMap<>();
    
    private ApiResult() {}
    
    public static ApiResult success() {
        ApiResult res = new ApiResult();
        return res;
    }
    
    public ApiResult put(String key,Object value) {
        this.result.put(key, value);
        return this;
    }

    public String getCode() { return code; }
    public void setCode(String code) { this.code = code; }
    public String getMsg() { return msg; }
    public void setMsg(String msg) { this.msg = msg; }
    public Map<String, Object> getResult() { return result; }
    public void setResult(Map<String, Object> result) { this.result = result; }
}

/**
Этот метод фактически такой же, как и предыдущий пример со сложной структурой Map параметров ответа, разница заключается в том, что один использует Map, а другой — объект ApiResut. Однако мы обнаружили, что этот метод описывает меньше аннотаций @LKARespose:
@LKARespose (names= {"код","сообщение"},values= {"Код состояния","Сообщение"})
Это связано с тем, что объект ApiResult уже описал свойства "code" и "msg" с помощью аннотации @LKAProperty. Lkadoc автоматически сканирует объекты ответа, помеченные аннотацией @LKAModel. Кроме того, если описание параметра аннотации @LKARespose совпадает со свойством объекта, описание параметра @LKARespose переопределит свойство объекта.
*/
@LKAMethod(value="Сложная структура объекта параметров ответа")
@LKAResposes({
        @LKARespose(name="общее количество",value="Общее количество записей",parentName="результат",parentValue="Данные ответа"),
        @LKARespose(type=User.class,parentName="пользователи",parentIsArray=true,parentValue="Список объектов пользователя",grandpaName="результат")
})
@PostMapping("getObj")
public ApiResult getObj() {
    List<User> users = new ArrayList<User>();
    User user1 = new User();
``` ```
user1.setName("张三");
User user2 = new User();
user2.setName("李四");
users.add(user1);
users.add(user2);
return ApiResult.success().put("total", 10).put("users", users);
}

//Этот метод аналогичен сложному методу тестирования объектов параметров ответа, единственное отличие состоит в том, что в type=User.class добавлено свойство group = "getUser", которое представляет данные только группы getUser
@LKAMethod(value="Параметры объекта ответа сгруппированы")
    @LKAResposes({
            @LKAResponse(name="total",value="Общее количество записей",parentName="result",parentValue="Данные ответа"),
            @LKAResponse(type=User.class,group = "getUser",parentName="users",parentIsArray=true,
                        parentValue="Список объектов пользователя",grandpaName="result")
    })
    @PostMapping("getObj2")
    public ApiResult getObj2() {
        List<User> users = new ArrayList<User>();
        User user1 = new User();
        user1.setName("张三");
        User user2 = new User();
        user2.setName("李四");
        users.add(user1);
        users.add(user2);
        return ApiResult.success().put("total",10).put("users",users);
    }

@LKADocument(basePackages="com.lkad.api",projectName = "Демонстрационный проект",description = "Используется для обучения Lkadoc",version = "1.0")
@SpringBootApplication
public class LkadocDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(LkadocDemoApplication.class, args);
    }
}

@LKADocument(basePackages="com.lkad.api",projectName = "Демонстрационный проект",description = "Для учебного проекта Lkadoc",version = "1.0",sconAll = true)
@SpringBootApplication
public class LkadocDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(LkadocDemoApplication.class, args);
    }
}

@LKAModel
public class Dept {
    private Integer id;
    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; }
}

@LKAMethod(value="Тест SconAll")
@RequestMapping("testSconAll")
public ApiResult testSconAll(Dept dept){
    return ApiResult.success();
}

@LKAMethod(value="Тест SconAll2")
@RequestMapping("testSconAll2")
public ApiResult testSconAll2(Integer age,String[] likes){
    return ApiResult.success();
}

@LKADocument(basePackages="com.lkad.api",projectName = "Демонстрационный проект",description = "Для учебного проекта Lkadoc",
version = "1.0",sconAll = true,serverNames = "Проект недвижимости^192.168.0.52:8081,Проект аренды жилья^192.168.0.77:8001")
@SpringBootApplication
public class LkadocDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(LkadocDemoApplication.class, args);
    }
}

*Здесь должно быть изображение.*

**Если пароль введён неверно, вы увидите страницу с ошибкой:**

*Здесь также должно быть изображение.*  

**Обратите внимание: помимо установки пароля для документа, в рабочей среде можно отключить функцию документа, установив значение свойства enabled равным false. Здесь это не демонстрируется.**

#### Функция сортировки интерфейса

**@LKAType и LKAMethod имеют атрибут order, который используется для настройки правил сортировки каталогов и интерфейсов. Чем меньше значение, тем выше приоритет.**

*Здесь тоже должно быть изображение.* 

#### Объединение каталогов и переключение интерфейсов между каталогами

Когда несколько классов имеют одинаковое значение аннотации @LKAType, Lkadoc объединяет их в один каталог. Также можно использовать атрибут directory аннотации @LKAMethod, чтобы указать вышестоящий каталог. Это позволяет переключать каталоги, но только если значение directory существует. Здесь это не демонстрируется, вы можете попробовать сами.

## Заключение

Спасибо за использование и поддержку, надеюсь, это будет полезно в вашей работе! Если вам нравится, пожалуйста, порекомендуйте его своим друзьям или коллегам. Обещаю пожизненную бесплатную поддержку! Если у вас возникнут проблемы во время использования или есть хорошие предложения, пожалуйста, оставьте мне комментарий, спасибо!

Адрес открытого исходного кода проекта: Gitee.com/liuk168/lkadoc.

**Не забудьте поставить звезду, если вам понравится!**

## Журнал обновлений

Версия 1.3.8 уже выпущена. Основные обновления включают:
1. Добавлена функция контроля того, является ли параметр отладки входящим.
2. В токен заголовка добавлено несколько параметров конфигурации, которые разделяются символом «;». Ключ и значение должны соответствовать друг другу.
3. Исправлена проблема с перекрытием перегруженных методов.
4. Добавлено автоматическое распознавание типа параметра с помощью аннотации `@LKAParam` (ранее работало только с аннотацией `@LKAParams`).
5. Оптимизирован базовый пакет сканирования. Атрибут classNum аннотации `@LKADocument` контролирует общее количество сканируемых классов по умолчанию (5000).
6. Оптимизация части кода и улучшение производительности инструмента.

Версия 1.3.9 уже выпущена. Основные обновления включают:
1. Исправлено неправильное распознавание типов выходных параметров, оптимизирована поддержка автоматического распознавания до 4 уровней обобщённых типов параметров. Более 4 уровней не имеет смысла, что указывает на проблему в программе.
2. Оптимизированный пользовательский интерфейс, более компактный и интуитивно понятный.
3. Оптимизированная часть бизнес-логики кода, улучшена стабильность инструмента.
4. Эта версия была выпущена 10 декабря 2021 года, и может возникнуть задержка при загрузке. Если загрузка не удалась, попробуйте через день или два. Спасибо!

Версия 2.0.0 уже выпущена. Основные обновления включают:
1. Удалены тестовые методы, оставшиеся от версии 1.3.9.
2. Убрана функция экспорта в PDF, оптимизирован код структуры (поскольку экспорт в формат MD можно преобразовать в PDF, эта функция избыточна).
3. Улучшена аннотация `@LKAParam`, ранее доступная только для методов, теперь она доступна и для параметров.
4. Оптимизировано контекстное меню помощника в пользовательском интерфейсе, которое автоматически отображает «Добавить» или «Удалить» в зависимости от состояния атрибута.
5. Оптимизирована структура проекта, удалена прослойка LKADocument, структура проекта стала более понятной.
6. Эта версия выпущена 5 мая 2022 года, и при загрузке может возникнуть задержка. Если загрузка не удалась, повторите попытку через день или два. Спасибо!