簡介

??Lkadoc是一款開源的接口文檔自動生成工具，基于SpringBoot平臺敬肚，擁有非常強大的接口文檔管理功能。為解決Java后臺開發(fā)人員編寫接口文檔鹰溜、調(diào)試接口而生斋日。同時提供了簡潔第献、大氣庸毫、功能豐富的接口文檔UI操作界面利花，方便后端與前端之間的接口對接炒事。

愿景

??我們愿成為java開發(fā)人員最好的基友，從手動編寫接口文檔的痛苦中解救出來睡扬，丟棄難用的Postman，工作效率從此翻倍韧涨，不再加班，有更多的時間陪伴家人娩贷。

特性

• 無侵入：引入它不會對現(xiàn)有項目產(chǎn)生影響彬祖。悄然降臨圆恤，寂靜無聲羽历。

• 整合方便：一個啟動注解就可以完成所有配置炼团。手到擒來币叹，唾手可得踩衩。

• 牛逼的注解：一個注解可描述多個參數(shù)驱富，多層參數(shù)結(jié)構(gòu)，甚至能做到接口零注解叫榕。登峰造極，縱橫天地荞下。

• 狂拽的調(diào)試：支持在線調(diào)試接口，同步抽诉、異步壓力測試接口掸鹅。喪心病狂葵姥，舉世無雙允乐。

• 酷炫的界面：文檔界面簡潔大氣蠢笋，能同時滿足前端和后端開發(fā)人員的審美觀昨寞。參數(shù)的展示方式可以在表格和JSON格式間自由切換。 如你所愿享怀，心隨我意。

• 強大的輔助：支持文檔聚合鳞贷、文檔下載悄晃、對象屬性分組、新接口標(biāo)記顯示眷蚓、動態(tài)修改參數(shù)狀態(tài)(高亮、標(biāo)記篙贸、說明)、全局綁定token寝贡、密碼驗證等強大的輔助功能加持圃泡。錦上添花价说，如虎添翼。

展示

自動生成的接口文檔UI頁面

新版風(fēng)格

接口調(diào)試頁面

在這里插入圖片描述

快速入門

用IDEA創(chuàng)建一個SpringBoot項目疑苔，項目名叫LkadocDemo，點擊Next

在這里插入圖片描述

勾選Spring web組件薪贫，點擊Finish

在這里插入圖片描述

在LkadocDemo項目的pom.xml文件中引入lkadoc的依賴（2.2.0版本于2022年5月5日發(fā)布，剛發(fā)布有可能拉取不下來鞍匾，有可能會延遲幾天，如果拉取不下來梁棠，可以先用1.4.0版本，1.4.0版及以上版本建議SpringBoot為2.6.X以上版本）

<!--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>

在LkadocDemo項目啟動類LkadocDemoApplication上加上@LKADocument注解

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

在com.lkad.api包下面準(zhǔn)備一個用戶登錄注冊模塊類-LKADemoController

@LKAType(value="用戶登錄注冊模塊")
@RestController
@RequestMapping("user")
public class LKADemoController {
 
        @LKAMethod(value="登錄")
        //@LKAParam(names= {"name","pwd"},values= {"用戶名","密碼"})
        @LKARespose(names= {"code","msg"},values= {"狀態(tài)碼","消息"})
        @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+"光臨本系統(tǒng)");
            return map;
        }
}

啟動項目沪伙，打開瀏覽器，輸入地址http://127.0.0.1:8080/lkadoc.html

在這里插入圖片描述

如果能看到如上界面翁授，那么就恭喜客官，Lkadoc能夠為您服務(wù)了

注解介紹

??Lkadoc 是基于注解來自動生成接口文檔的塞赂，注解功能非常強大，要想靈活的使用 Lkadoc仇哆，那么就必須掌握注解相關(guān)的知識讹剔。Lkadoc為 swagger 大部分注解做了兼容處理，只需修改引入的包路徑為com.lk.api.*即可衫冻。

@LKADocument

#@LKADocument是加在SpringBoot啟動類上的注解，必須加上为居，否則Lkadoc接口文檔不可使用蒙畴，用來描述項目信息碑隆，該注解下的屬性可以代替application配置文件里面的lkad相關(guān)配置，非常方便劫狠，常用屬性：

basePackages:掃描接口的包路徑，多個用","號隔開懦砂，指定父包路徑可以掃描所有父包下的子包路徑【必須】
#例如:basePackages="com.lkad.api,com.lkad.admin"

projectName:項目名稱【可選】
#例如:projectName="Lkadoc測試項目"

description:項目描述【可選】
#例如:description="該項目用來教學(xué)Lkadoc的使用"

serverNames:要聚合的項目地址，"^"前面是項目名稱（可省略）衫画，后面是項目的地址（也可以用域名）削罩，多個用","號隔開，用來聚合其它項目的接口信息微服，可以在UI界面切換【可選】
#例如:serverNames="物業(yè)項目^192.168.0.52:8081,租房系統(tǒng)^192.168.0.77:8001"

version:項目的版本號,配合@LKAMethod注解的version屬性可以快速定位新接口【可選】
#例如:version="1.0"

enabled:接口文檔啟動開關(guān),true是開啟，false是禁用,默認(rèn)為開啟【可選】
#例如:enabled=true

sconAll:是否開啟對未加注解描述的參數(shù)進行自動識別丛肮，默認(rèn)為false【可選】
#例如:sconAll=false

password:設(shè)置查看接口文檔所需的密碼，默認(rèn)不需要密碼【可選】
#例如:password="123456"

注意：@LKADocument注解相關(guān)屬性也可以在application.properties文件中通過lkad.basePackages="x.x.x"的方式配置习劫，但@LKADocument這個注解不能省略搞疗。如果application.properties文件中配置了lkad屬性桩皿，那么@LKADocument注解中的屬性會全部失效拒贱，意思就是說兩種方式只能二選一

@LKAType

#用來描述類的信息逻澳，常用屬性：

value:類的作用【必須】
#例如:value="測試類"

description:類的描述【可選】
#例如:description="該類只是用來測試"

hidden:是否在UI界面隱藏該類的信息，默認(rèn)為false瓤逼，如果設(shè)置為ture那么該類下在的所有接口也會隱藏【可選】
#例如:hidden=false

order:排序，值越少越靠前【可選】
#例如:order=1

@LKAMethod

#用來描述接口的信息诱告，常用屬性：

value:接口的作用【必須】
#例如:value="用戶登錄"

description:接口的描述【可選】
#例如:description="用于APP端登錄的接口"

contentType:請求頭ContentType類型，默認(rèn)為application/x-www-form-urlencoded【可選】
#例如:contentType="application/json"

author:作者【可選】
#例如:author="L.K"

createTime:接口創(chuàng)建時間【可選】
#例如:createTime="2021-08-08"

updateTime:接口修改時間【可選】
#例如:updateTime="2021-10-01"

hidden:是否在UI界面隱藏該接口箱蟆，默認(rèn)為false【可選】
#例如:hidden=false

version:接口版本號，如果項目版本號相同辈毯，在UI界面會標(biāo)記為新接口【可選】
#例如:version="1.0"

download:是否是下載的方法钝凶，如果該接口涉及到下載文件必須設(shè)置成true，默認(rèn)是false【可選】
#例如:download=false

token:是否需要token驗證哟沫，只標(biāo)識該接口需要token驗證嗜诀，不會影響正常業(yè)務(wù)，默認(rèn)是true【可選】
#例如:token=true

order:排序拂蝎，數(shù)字越少越靠前【可選】
#例如:order=1

directory:指定上級目錄（這里目錄是指@LKAType的value屬性值，上級目錄必須存在捣作，不然不會展示在接口文檔，默認(rèn)當(dāng)前類的目錄）【可選】
#例如:directory="用戶管理"

@LKAParam / @LKAParams

#用來描述請求參數(shù)的信息也拜，帶s復(fù)數(shù)屬性代表可以設(shè)置多個參數(shù),但要注意參數(shù)順序。帶s和不帶s設(shè)置時只能二選一卵贱，建議大家不管是多個參數(shù)還是單個參數(shù)，都用帶s復(fù)數(shù)屬性，帶s復(fù)數(shù)屬性要更靈活碾局，更智能。常用屬性：

name/names:參數(shù)名稱【必須】（用name設(shè)置參數(shù)名稱時必須;用names設(shè)置參數(shù)名稱時可省略镐牺，但JDK版本要1.8以上募胃，編譯的時候還要加上–parameters啟動參數(shù)检疫，這樣Lkadoc可自動獲取到參數(shù)名稱,目前測試JDK11不加–parameters參數(shù)也可以識別參數(shù)名稱屎媳，否則必須）
#例如:
#單個參數(shù)配置:name="name"
#多個參數(shù)配置:names={"name","pwd","age"} //這里如果和接口入?yún)㈨樞蛞粯樱墒÷圆挥门渲?#或者丹禀，
#@LKAParams({
    #@LKAParam(name="name",...),
    #@LKAParam(name="pwd",...),
    #@LKAParam(name="age",...)
#})
#注意，@LKAParams用法的其它屬性才name都一樣焙矛，后面不再舉例贫导。

value/values:參數(shù)作用【必須】
#例如:
#單個參數(shù)配置:value="姓名"
#多個參數(shù)配置:values={"姓名","密碼","年齡"}

description/descriptions:參數(shù)的描述【可選】
#例如:
#單個參數(shù)配置:description="姓名不能超過5個漢字"
#多個參數(shù)配置:descriptions={"姓名不能超過5個漢字","密碼不能少于6位","年齡在18歲和60歲之間"}

dataType/dataTypes:數(shù)據(jù)類型【可選】（用dataType配置時默認(rèn)值String.class;用dataTypes配置時可自動獲取參數(shù)的數(shù)據(jù)類型脱盲，可省略不配置，但要注意參數(shù)的順序面哥。）
#例如:
#單個參數(shù)配置:dataType=String.class //這里可省略，因為默認(rèn)是String
#多個參數(shù)配置:dataTypes={String.class,Date.class,Integer.class} //如果和接口入?yún)㈨樞蛞恢驴墒÷宰詣荧@取

required/requireds:是否必傳吱涉，默認(rèn)為true【可選】(更簡便的用法是在name屬性值后面加"-n"或者在value屬性值前面加“n~”代表非必傳參數(shù))
#例如:
#單個參數(shù)配置:required=false 或者 name="name-n" 或者 value="n~用戶名" //三種方式都代表非必傳（3選1）
#多個參數(shù)配置:#requireds={false,true,false} 
#或者 names={"name-n","pwd","age-n"} 
#或者 values={"n~用戶名","密碼","n~年齡"} //三種方式效果都一樣，用戶名和年齡非必傳鳖链，密碼必傳（3選1）

paramType/paramTypes:參數(shù)位置，query灌侣、header顶瞳、path三選一【可選】（用paramType配置時默認(rèn)為query;用paramTypes配置時Lkadoc可根據(jù)參數(shù)注解@PathVariable、@RequestHeader自動獲取參數(shù)位置符喝，可省略不配）
#例如:
#單個參數(shù)配置:paramType="query" //默認(rèn)是query,可以省略不配置
#多個參數(shù)配置:paramTypes={"query","header","path"} //參數(shù)如果加上了@PathVariable畏腕、@RequestHeader注解，可自動獲取參數(shù)位置铭污，可省略不配置

isArray/isArrays:該參數(shù)是否是集合或數(shù)組嘹狞，默認(rèn)false【可選】
#例如:
#單個參數(shù)配置:isArray=false
#多個參數(shù)配置:isArrays={false,true,false}

testData/testDatas:測試數(shù)據(jù)【可選】(更簡便的用法是在value后面的"^"符號后面加上測試數(shù)據(jù))
#例如:
#單個參數(shù)配置:testData="張三" 或者 value="姓名^張三" //兩種方式2選1
#多個參數(shù)配置:testDatas={"張三","123456","22"} 
#或者 values={"n~姓名^張三","密碼^123456","n~年齡^22"} //兩種方式2選1 

type:入?yún)ο箢愋汀究蛇x】（當(dāng)接口請求參數(shù)是一個對象時使用，但一般不需要設(shè)置涧偷，可自動識別）
#例如:type=User.class  //一般不用配置，可自動識別

group:和type配合使用，對象參數(shù)分組唉锌，可過濾沒必要的參數(shù)【可選】
#例如:group="add"  //add是一個組名，事先在User對象的參數(shù)上面配置好的

@LKAModel

#用來描述實體類的信息
#常用屬性：
value:屬性的作用【可選】
description:屬性的描述【可選】

@LKAProperty

#用來描述實體類的屬性的信息绿语，和@LKAParam注解屬性用法差不多，這里不再舉例了
#常用屬性:
value:屬性的作用【必須】
description:屬性的描述【可選】
hidden:是否在UI界面隱藏該屬性匹耕，默認(rèn)為false【可選】
testData:測試數(shù)據(jù)【可選】（更簡便的用法是在value后面的"^"符號后面加上測試數(shù)據(jù)）
required:是否必傳驶赏，默認(rèn)為true【可選】（更簡便的用法是在value前面加"n~"代表非必傳）
isArray:是否是數(shù)組或集合煤傍，不設(shè)置也可自動識別【可選】
type:當(dāng)屬性為對象類型時，可以用type來指定蒋失，不設(shè)置也可自動識別【可選】
groups:用來進行參數(shù)分組設(shè)置，可設(shè)置多個組名【可選】（required在分組時用法是在groups屬性里面的組名后面加"-n"代表不是必傳铣卡，不加默認(rèn)是必傳）
#例如: groups={"add","update-n","info"}

@LKAGroup

#@LKAGroup是一個入?yún)⒆⒔猓饔檬侵付▽ο笫悄慕M參數(shù)用來作為入?yún)?

@LKARespose/@LKAResposes

#用來描述響應(yīng)參數(shù)的信息,和@LKAParam注解屬性用法差不多蝉仇，這里不再舉例了
#常用屬性
name/names:參數(shù)名稱轿衔，和type參數(shù)二選一【必須】
value/values:參數(shù)作用【必須】
description/descriptions:參數(shù)的描述【必須】
dataType/dataTypes:參數(shù)數(shù)據(jù)類型，當(dāng)使用dataTypes不設(shè)置也可以自動識別【可選】
isArray/isArrays:是否是集合或數(shù)組宛官，默認(rèn)false【可選】
type:出參對象類型，和name/names參數(shù)二選一枷恕，可自動識別【可選】
group:和type配合使用未玻，對象參數(shù)分組扳剿，可過濾沒必要的參數(shù)【可選】
#父參數(shù)
parentName:父參名稱【可選】
parentValue:父參作用【可選】
parentDescription:父參描述【可選】
parentIsArray:父參是否是數(shù)組或集合【可選】
#爺參數(shù)
grandpaName:爺參名稱【可選】
grandpaValue:爺參作用【可選】
grandpaDescription:爺參描述【可選】
grandpaIsArray:爺參是否是數(shù)組或集合【可選】

基礎(chǔ)應(yīng)用

??在基礎(chǔ)應(yīng)用中，我會用大量的案例來演示各種場景Lkadoc的使用方法和技巧瞧掺，能夠讓大家在案例中快速掌握Lkadoc的基本使用。同時你也能從中體會到Lkadoc的便利與強大哼转。

簡單的請求入?yún)⑹纠?/h4>

以快速入門的案例為基礎(chǔ)，修改@LKADocument注解如下

//增加項目名稱和和項目說明
@LKADocument(basePackages="com.lkad.api",projectName = "演示項目",description = "用于Lkadoc教學(xué)項目")
@SpringBootApplication
public class LkadocDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(LkadocDemoApplication.class, args);
    }
}

在LKADemoController類下面我們再增加一個注冊的方法

//注意:JDK8及以上@LKAParam注解的names={"name","pwd","email","age"}配置可省略
@LKAMethod(value="用戶注冊",description="APP的注冊接口",version="1.0",createTime="2021-08-08",author="LK")
@LKAParam(names={"name","pwd","email","age"},values= {"用戶名^張凡","密碼^123abc","n~郵箱^123@qq.com","n~年齡^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 "注冊成功";
}

啟動項目佣蓉，打開瀏覽器，輸入地址http://127.0.0.1:8080/lkadoc.html ，界面如下：

在這里插入圖片描述

path和header請求入?yún)⑹纠?/h4>

再增加一個path和header入?yún)⒌臏y試方法，Lkadoc能夠自動識別@RequestHeader周崭、@PathVariable注解

@LKAMethod(value="path和header入?yún)?)
@LKAParam(names={"token","name","email"},values= {"令牌^aaaa","n~姓名^瓜瓜","n~郵箱^123@qq.com"})
@PostMapping("getUser/{name}/{email}")
public String getUser(@RequestHeader("token") String token,
                      @PathVariable("name") String name,
                      @PathVariable("email") String email) {

    return "測試結(jié)果：token="+token+",name="+name+",email="+email;
}

重啟項目续镇，刷新Lkadoc界面如下:

在這里插入圖片描述

數(shù)組請求入?yún)⑹纠?/h4>

再增加一個數(shù)組入?yún)⒌臏y試方法

//isArrays = {true,false}代表第一個參數(shù)是數(shù)組制跟，第二參數(shù)不是數(shù)組
@LKAMethod(value="數(shù)組入?yún)?)
@LKAParam(names={"ids","name"},values= {"用戶ID^1001","n~姓名^瓜瓜"},isArrays = {true,false})
@PostMapping("array")
public String array(Integer[] ids,String name) {

    return "測試結(jié)果：ids="+ Arrays.toString(ids)+",name="+name;
}

重啟項目，刷新Lkadoc界面如下:

在這里插入圖片描述

文件上傳請求入?yún)⑹纠?/h4>

再增加一個文件上傳測試方法

//ContentType.FORMDATA常量的值為multipart/form-data
@LKAMethod(value="文件批量上傳",contentType=ContentType.FORMDATA)
@LKAParam(names= "files",values="上傳文件",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;
}

重啟項目排监，刷新Lkadoc界面如下:

在這里插入圖片描述

文件下載示例

再增加一個文件下載的測試方法

//@LKAMethod注解的download=true代表這個方法是一個文件下載的方法，測試這個方法事先要在D盤準(zhǔn)備一個test.txt文件峭弟。至于文件下載的業(yè)務(wù)邏輯，這里不做講解情臭。
@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();
}

重啟項目，刷新Lkadoc界面如下:

在這里插入圖片描述

簡單的對象請求入?yún)⑹纠?/h4>

??當(dāng)我們?nèi)雲(yún)⑹且粋€對象時跷乐，如果該對象上有@LKAModel注解，并且它的屬性上有@LKAProperty注解浅侨，那么Lkadoc會去自動掃描這個對象信息如输，我們無需在接口上加額外的注解去描述對象參數(shù)澳化。這樣如果我們用對象去操作入?yún)⒌脑挘梢源蟠鬁p少接口上的注解數(shù)量慎陵，顯得更加簡潔。

在com.lkad.model包下面準(zhǔn)備一個角色對象

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

增加一個簡單的對象請求入?yún)⒌臏y試方法

@LKAMethod("基本對象入?yún)?)
@GetMapping("getRole")
public Role getRole(Role role) {
    return role;
}

重啟項目润梯，刷新Lkadoc界面如下:

在這里插入圖片描述

復(fù)雜的對象請示入?yún)⑹纠?/h4>

在com.lkad.model包下再增加兩個對象address和User，加上之前Role一共有3個對象

@LKAModel
public class Address {
    @LKAProperty(value="地址ID^1")
    private Integer id;
    @LKAProperty(value="n~地址信息^深圳市龍華區(qū)")
    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="n~年齡^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; }
}

增加一個復(fù)雜的對象請求入?yún)⒌臏y試方法

/**
1.復(fù)雜的對象需把@LKAMethod注解的contentType屬性設(shè)置為"application/json"
2.如果contentType="application/json"，需在接收對象參數(shù)前面加@RequestBody注解
3.如果contentType="application/json"竟纳，那么接口的請求類型不能是get
*/
@LKAMethod(value="復(fù)雜的對象傳參",contentType=ContentType.JSON)
@PostMapping("addUser")
public User addUser(@RequestBody User user) {
    return user;
}

重啟項目，刷新Lkadoc界面如下:

在這里插入圖片描述

通過點擊"樹狀展示請求參數(shù)"按鈕桶略，可以很直觀的顯示復(fù)雜的入?yún)⒔Y(jié)構(gòu)

在這里插入圖片描述

對象參數(shù)分組示例

??我們感受到了用對象接收請求參數(shù)更具便利性，那怎么去過濾對象屬性呢蹬挺？例如：有一個查詢接口，只用到user對象的name虐秋、age參數(shù)和addresses對象的info參數(shù)用押，但對于前端的友好度，我們不需要展示所有對象屬性到Lkadoc界面缎讼，這時我們就可以用對象參數(shù)分組來實現(xiàn)血崭。

• 分組可以用@LKAProperty注解的groups屬性來設(shè)置組名
• 一個屬性可以屬于多個組，組名不能重復(fù)舰讹，多個組名用","號隔開
• 組名沒有任何限制跺涤，只要不是空白的字符串即可
• 如果用到嵌套對象里面屬性，嵌套對象名稱和對應(yīng)屬性上都要設(shè)置相同的組名
• 入?yún)ο笮枰聾LKAGroup注解來指定對象是哪組參數(shù)用來作為入?yún)?/li>

//@LKAProperty注解的groups屬性可以用來實現(xiàn)參數(shù)分組院刁，多個分組可以用英文","隔開。組名"getUser-n"狡刘，這個"-n"代表這個參數(shù)在這組數(shù)據(jù)里面是非必傳參數(shù)
@LKAModel
public class User {
    @LKAProperty(value="用戶ID^1001")
    private Integer id;
    @LKAProperty(value="n~用戶名稱^張三",groups = {"getUser","getUser2"})
    private String name;
    @LKAProperty(value="n~年齡^20",description="范圍0-120",groups = {"getUser-n"})
    private String age;
    @LKAProperty(value="角色對象")
    private Role role;
    @LKAProperty(value="用戶愛好^運動")
    private String[] likes;
    @LKAProperty(value="地址信息",groups = {"getUser"})//這里的groups = {"getUser"}不能省略
    private List<Address> addresses; 
    ...get和set方法（略）...
}

@LKAModel
public class Address {
    @LKAProperty(value="地址ID^1")
    private Integer id;
    @LKAProperty(value="n~地址信息^深圳市龍華區(qū)",groups= {"getUser-n"})
    private String info;
    .......get和set方法（略）.......
}

新增一個對象參數(shù)分組的測試方法

//在入?yún)ο骍ser前面加一個注解@LKAGroup("getUser")剑按，代表在Lkadoc只需展示組名為getUser的數(shù)據(jù)
@LKAMethod(value="對象參數(shù)分組",contentType=ContentType.JSON)
@PostMapping("getUserArray")
public User getUserArray(@RequestBody @LKAGroup("getUser") User user) {
    return user;
}

重啟項目艺蝴，刷新Lkadoc界面如下:

在這里插入圖片描述

簡單的響應(yīng)參數(shù)示例

在com.lkad.api包下面準(zhǔn)備一個用戶業(yè)務(wù)模塊類-LKADemoController2，并準(zhǔn)備一個簡單的響應(yīng)出參測試方法

@LKAType(value="用戶業(yè)務(wù)模塊")
@RestController
@RequestMapping("business")
public class LKADemoController2 {

    @LKAMethod("簡單的響應(yīng)出參")
    @LKARespose(names= {"code","msg","data"},values= {"狀態(tài)碼","消息","數(shù)據(jù)"})
    @GetMapping("getInfo")
    public Map<String,Object> getInfo() {
        Map<String,Object> map = new HashMap<>();
        map.put("code",200);
        map.put("msg","獲取信息成功");
        map.put("data","響應(yīng)數(shù)據(jù)");
        return map;
    }
}

重啟項目，刷新Lkadoc界面如下:

在這里插入圖片描述

對象響應(yīng)參數(shù)示例

在LKADemoController2類下面再增加一個對象出參的測試方法

//不管是入?yún)⑦€是出參如果是一個對象撇叁，且對象有加@LKAModel及屬性有加@LKAProperty注解，那么Lkadoc會自動掃描該出參對象
@LKAMethod(value="對象出參",contentType=ContentType.JSON)
@PostMapping("getUser")
public User getUser(@RequestBody User user) {
    return user;
}

重啟項目趋厉，刷新Lkadoc界面響應(yīng)參數(shù)展示結(jié)果如下:

在這里插入圖片描述

復(fù)雜的Map結(jié)構(gòu)響應(yīng)參數(shù)示例

在LKADemoController2類下面再增加一個復(fù)雜的Map結(jié)構(gòu)響應(yīng)參數(shù)的測試方法

@LKAMethod(value="復(fù)雜的Map結(jié)構(gòu)響應(yīng)參數(shù)")
@LKAResposes({
    @LKARespose(names= {"code","msg"},values= {"狀態(tài)碼","消息"}),
    @LKARespose(name="total",value="總記錄數(shù)",parentName="result",parentValue="響應(yīng)數(shù)據(jù)"),
    @LKARespose(type=User.class,parentName="users",parentIsArray=true,parentValue="用戶對象列表",grandpaName="result")
})
@GetMapping("getMap")
public Map<String,Object> getMap() {
    Map<String,Object> map = new HashMap<>();
    map.put("code",200);
    map.put("msg","操作成功！");
    Map<String,Object> data = new 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;
}

重啟項目乡数，刷新Lkadoc界面響應(yīng)參數(shù)展示結(jié)果如下:

在這里插入圖片描述

通過點擊"樹狀展示響應(yīng)參數(shù)"按鈕，可以很直觀的顯示復(fù)雜的響應(yīng)參數(shù)結(jié)構(gòu)

在這里插入圖片描述

超過3層嵌套結(jié)構(gòu)響應(yīng)參數(shù)用法示例

??通過parentXXX和grandPaXXX相關(guān)屬性用一條@LKARespose注解只能一次性描述1到3級節(jié)點，如果有5級或者10級節(jié)點該怎么辦金度？ 也有解決辦法猜极，非常簡單扎筒，但注解可能會比較多，例如有這么一個結(jié)構(gòu){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”)

在LKADemoController2類下面再增加一個超過3層嵌套結(jié)構(gòu)用法技巧的測試方法

@LKAMethod(value="超過3層嵌套結(jié)構(gòu)用法技巧")
@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")
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;
}

重啟項目，刷新Lkadoc界面響應(yīng)參數(shù)展示結(jié)果如下:

在這里插入圖片描述

JSON格式化展示

在這里插入圖片描述

復(fù)雜的對象結(jié)構(gòu)響應(yīng)參數(shù)示例

??在實際工作開發(fā)中相满，我們往往會準(zhǔn)備一個封裝好的響應(yīng)參數(shù)對象來統(tǒng)一規(guī)范化接口的出參，現(xiàn)在我們來演示一下建蹄，把上面那復(fù)雜的Map結(jié)構(gòu)響應(yīng)參數(shù)示例改造成對象結(jié)構(gòu)洞慎。

準(zhǔn)備一個響應(yīng)封裝對象

@LKAModel
public class ApiResult {
    @LKAProperty(value="狀態(tài)碼")
    private String code;
    @LKAProperty(value="消息")
    private String msg;
    @LKAProperty(value="響應(yīng)數(shù)據(jù)")
    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; }
}

在LKADemoController2類下面再增加一個復(fù)雜的對象結(jié)構(gòu)響應(yīng)參數(shù)的測試方法

/**
     這個方法其實和上面復(fù)雜的Map結(jié)構(gòu)響應(yīng)參數(shù)示例是一樣的鸟妙，不一樣的地方是一個是Map,一個是ApiResut對象重父。但是我們發(fā)現(xiàn)這個方法在響應(yīng)參數(shù)描述是少用一個注解：
     @LKARespose(names= {"code","msg"},values= {"狀態(tài)碼","消息"})
     這是因為ApiResult對象已經(jīng)通過@LKAProperty注解描述過"code","msg"屬性了个从，Lkadoc會去自動掃描帶有@LKAModel注解的響應(yīng)對象嗦锐。還有如果@LKARespose注解描述的參數(shù)和對象里面的屬性一致的話，@LKARespose注解描述的參數(shù)會覆蓋掉對象里面的屬性
     */
    @LKAMethod(value="復(fù)雜的對象結(jié)構(gòu)響應(yīng)參數(shù)")
    @LKAResposes({
            @LKARespose(name="total",value="總記錄數(shù)",parentName="result",parentValue="響應(yīng)數(shù)據(jù)"),
            @LKARespose(type=User.class,parentName="users",parentIsArray=true,parentValue="用戶對象列表",grandpaName="result")
    })
    @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);
    }

重啟項目碳默，刷新Lkadoc界面響應(yīng)參數(shù)展示結(jié)果如下髓废，實際上和上面復(fù)雜的Map結(jié)構(gòu)響應(yīng)參數(shù)示例結(jié)果是一樣的:

在這里插入圖片描述

通過點擊"樹狀展示響應(yīng)參數(shù)"按鈕，可以很直觀的顯示復(fù)雜的響應(yīng)參數(shù)結(jié)構(gòu)

在這里插入圖片描述

響應(yīng)參數(shù)對象參數(shù)分組

??@LKARespose注解的group屬性也可以實現(xiàn)響應(yīng)參數(shù)分組冈爹，使用原理和請求參數(shù)分組是一樣的频伤。

在LKADemoController2類下面增加一個響應(yīng)參數(shù)對象參數(shù)分組測試方法

//這個方法上面復(fù)雜的對象結(jié)構(gòu)響應(yīng)參數(shù)測試方法是一樣的，唯一不同的是在type=User.class增加了group = "getUser"屬性配置瞬哼，代表只展示getUser組的數(shù)據(jù)
@LKAMethod(value="響應(yīng)參數(shù)對象參數(shù)分組")
    @LKAResposes({
            @LKARespose(name="total",value="總記錄數(shù)",parentName="result",parentValue="響應(yīng)數(shù)據(jù)"),
            @LKARespose(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);
    }

重啟項目，刷新Lkadoc界面響應(yīng)參數(shù)展示結(jié)果如下：

在這里插入圖片描述

高級特性

??Lkadoc提供了很多非常實用的特色功能结胀，這些特色功能可以給大家在使用Lkadoc工具時帶來如虎添翼的效果糟港。有了這些特色功能的加持秸抚，能夠助你迅速調(diào)試接口剥汤，快定定位錯誤吭敢，連測試代碼都不用寫了欲低。還能大大提高與前端對接口的效率砾莱，簡直堪稱接口神器腊瑟！

調(diào)試API功能

??Lkadoc支持對單個接口進入調(diào)試魔策，我們只需要準(zhǔn)備好請求參數(shù)的測試數(shù)據(jù)虎敦，然后點擊"執(zhí)行接口"按鈕其徙，就可以在調(diào)試窗口看到調(diào)試結(jié)果信息了唾那。

在這里插入圖片描述

??Lkadoc還可以通過選擇執(zhí)行方式來決定接口采用"同步"還是"異步"執(zhí)行，如果選擇"同步"測試避诽，可以選擇執(zhí)行次數(shù)沙庐，和時間間隔，這樣可以模擬對接口進行壓力測試古涧。如果選擇"異步"測試羡滑，可以選擇執(zhí)行次數(shù)柒昏，這樣可以模擬對接口進行并發(fā)測試职祷。所有測試結(jié)果會打印在調(diào)試窗口中是尖。

在這里插入圖片描述

全局請求頭令牌(Token)鎖定

??我們在調(diào)試需要token授權(quán)的接口時,需要在每個需要授權(quán)接口的請求頭帶上一個類似token的參數(shù)饺汹，調(diào)試時非常不方便，所以Lkadoc提供了一個可以給全局接口鎖定一個請求頭參數(shù)夸溶，這樣就不需要在每一個需要授權(quán)的接口中去設(shè)置這個授權(quán)參數(shù)了扫皱。

??同時我們可以通過@LKAMethod的token屬性來控制當(dāng)前接口是否需要token校驗啸罢，如果token=true的話，那么在Lkadoc調(diào)試接口的時候衩匣，會自動帶上鎖定的請求頭參數(shù)到后臺琅捏。

在這里插入圖片描述

快速定位新接口

??大家應(yīng)該還有印象，在用@LKADocument注解配置項目信息時有一個version屬性用來設(shè)置項目的版本號市俊，然后@LKAMethod注解也有一個version屬性用來設(shè)置接口的版本號摆昧，在實際工作中，往往一個項目版本升級并不代表所有接口都需要升級忌锯，也可能會增加一些新接口偶垮。那么我們怎么才能在眾多的接口中定位哪一個接口是新接口或最新修改的接口呢晶伦？很簡單婚陪，我們只需把新接口或最新修改的接口的@LKAMethod注解version屬性的版本值設(shè)置和@LKADocument注解的version屬性的版本值設(shè)置成一致就可以了，這樣Lkadoc會用星星標(biāo)記出新接口脆淹。那么后端在和前端同事對接口時就可以很快定位哪些是新接口了

修改@LKADocument注解如下，新增version="1.0"的屬性配置

@LKADocument(basePackages="com.lkad.api",projectName = "演示項目",description = "用于Lkadoc教學(xué)項目",version = "1.0")
@SpringBootApplication
public class LkadocDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(LkadocDemoApplication.class, args);
    }
}

然后我們看一下用戶注冊方法烘嘱，里面有配置 version="1.0"的屬性配置，這個接口的版本號和項目的版本號是一致的哮内，代表這是一個新接口纹因，同時用戶注冊接口一般是不需要token校驗的辐怕，這里我們設(shè)置token=false

//注意:JDK8及以上@LKAParam注解的names={"name","pwd","email","age"}配置可省略
@LKAMethod(value="用戶注冊",description="APP的注冊接口",version="1.0",createTime="2021-08-08",author="LK",token=false)
@LKAParam(names={"name","pwd","email","age"},values= {"用戶名^張凡","密碼^123abc","n~郵箱^123@qq.com","n~年齡^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 "注冊成功";
}

重啟項目从绘，刷新Lkadoc頁面如下:

在這里插入圖片描述

自動識別未加注解參數(shù)

??當(dāng) @LKADocument 的 sconAll=true 時寄疏，會把接口的所有參數(shù)掃描出來，部分沒有加@LKAProperty和@LKAParam注解的參數(shù)并沒有設(shè)置作用描述之類的信息僵井，那么就可以通過“自定義作用”動態(tài)的添加該參數(shù)的作用說明陕截，當(dāng)然也可以修改已經(jīng)設(shè)置好的作用說明。

修改@LKADocument注解如下批什，新增sconAll=true 的屬性配置

@LKADocument(basePackages="com.lkad.api",projectName = "演示項目",description = "用于Lkadoc教學(xué)項目",version = "1.0",sconAll = true)
@SpringBootApplication
public class LkadocDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(LkadocDemoApplication.class, args);
    }
}

新增一個實體類乳规， 屬性不加任何注解冻辩，但@LKAmodel注解必須加上

@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();
}

重啟項目咙咽，刷新文檔頁面如下：

[圖片上傳失敗...(image-57c680-1626143527983)]

[圖片上傳失敗...(image-8512ad-1626143527983)]

我們可以發(fā)現(xiàn)入?yún)⒍伎梢宰R別出來犁享，同時我們可以通過在參數(shù)名稱上點擊鼠標(biāo)右鍵凤巨，修改參數(shù)作用說明，還可以設(shè)置高亮和刪除狀態(tài)

在這里插入圖片描述

在這里插入圖片描述

項目聚合

??當(dāng)我們在使用微服務(wù)或多個項目時捧颅，我們可以把多個項目的接口文檔信息聚合到一個UI界面扣典，只需要配置@LKADocument注解的serverNames屬性即可远舅，多個項目之間用英文“,”號隔開任连，“^”符號左邊是項目名稱拱她，右邊是項目地址唬复，也可以是域名休建，這樣我們就可以在Lkadoc界面自由的在當(dāng)前項目和配置好的其它項目切換接口信息了邑彪。

修改@LKADocument注解如下有巧，新增serverNames 的屬性配置

@LKADocument(basePackages="com.lkad.api",projectName = "演示項目",description = "用于Lkadoc教學(xué)項目",
version = "1.0",sconAll = true,serverNames = "物業(yè)項目^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);
    }
}

重啟項目逊笆，刷新文檔如下：

在這里插入圖片描述

文檔導(dǎo)出功能

??Lkadoc還提供了導(dǎo)出功能乃戈，Lkadoc支持導(dǎo)出標(biāo)準(zhǔn)化格式的PDF或MarkDown接口文檔谍憔，功能非常強大需忿，能滿足大部分場景需求汗洒。（目前只支持導(dǎo)出本地項目的接口）
??導(dǎo)出PDF文檔前需要檢查系統(tǒng)是否存在simsun.ttc字體肝集，如果系統(tǒng)沒有這個字體的話浮创，導(dǎo)出PDF文檔中文不能正確顯示斩祭。 windows系統(tǒng)字體路徑：C:/Windows/fonts/simsun.ttc
linux系統(tǒng)字體路徑：/usr/share/fonts/win/simsun.ttc
mac系統(tǒng)字體路徑：/System/Library/Fonts/simsun.ttc

在這里插入圖片描述

PDF效果：

在這里插入圖片描述

MarkDown效果：

在這里插入圖片描述

給Lkadoc設(shè)置查看密碼

修改@LKADocument注解如下邪乍，新增 password 的屬性配置

@LKADocument(basePackages="com.lkad.api",projectName = "演示項目",description = "用于Lkadoc教學(xué)項目",
version = "1.0",sconAll = true,serverNames = "物業(yè)項目^192.168.0.52:8081,租房項目^192.168.0.77:8001",password = "123")
@SpringBootApplication
public class LkadocDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(LkadocDemoApplication.class, args);
    }
}

重啟項目睛驳，刷新文檔，這樣就需要先輸入密碼才能進入Lkadoc界面：

在這里插入圖片描述

如果密碼錯誤就進入錯誤提示頁面：

在這里插入圖片描述

注意：除了給文檔設(shè)置密碼之外菲驴，在生產(chǎn)環(huán)境薯蝎，還可以通過設(shè)置enabled屬性值為false來關(guān)閉文檔功能，這里就不演示了。

接口排序功能

@LKAType 和 LKAMethod 都提示了一個order屬性挺物，用來設(shè)置目錄和接口的排序規(guī)則，值越少柱彻，那么就越靠前。

在這里插入圖片描述

目錄合并和接口切換目錄

??當(dāng)多個類的@LKAType注解value值相同時伟叛，Lkadoc會把它們合并到一個目錄管理匀奏，同時還可以通過@LKAMethod的directory屬性來指定它的上一級目錄。達到切換目錄的目的焕阿，前提是directory的值必須存在。這里就不演示了，大家可以自己去嘗試一下墓律。

結(jié)尾

??感謝您的使用與支持饼记，希望它能夠在工作中給您帶來便利匪凡！如果覺得好用請推薦給您身邊需要的朋友或同事。承諾終身免費兼砖，免費提供技術(shù)支持！如果您在使用過程中遇到問題或者有好的建議众旗，請給我留言，謝謝晌柬！

項目開源地址：碼云->https://gitee.com/liuk168/lkadoc
如果大家學(xué)得好用涤久，記得給星哦