前言：其實我是個開發Android的，爲什麼回想着去寫一個後臺文檔生成工具呢，這就要從很久以前說起…扯遠了，其實主要的原因是，現在的Api文檔生成工具好用的不好看，好看的要花錢，好看好用的不會用，所以就當誕生了現在自主開發的文檔生成器：MiApiDoc
MiApiDoc主要用於Spring系列的項目，比如Spring
mvc,SpringBoot等等，理論上只要用到GetMapping、PostMapping的項目，MiApiDoc都有很好的體驗，其他不是Spring相關的項目也可以使用，方法都是一樣，只是有些便捷功能不支持而已。
進入主題
本工具需要配合另外一個web網頁使用，地址：好看的Spring項目文檔生成工具-MiApiDoc(2)。
本工具GitHub地址，只需要引入裏面的jar包即可，TestMain有實例代碼。
先上圖片：
第一個實例：
MiApiDoc.Builder()
.setDirectory(MiApiDocDirectory("用戶端","user.json",60*60*24))
//創建一個目錄，該目錄下的所有生成的數據保存在‘user.json’，如果Api有改動，web提示時長爲一天，可多個
.setDefaultHostUrl("http://192.168.3.5:9096/")
//請求的跟路徑
.setScanningPackages("top.mish.mxsh.Controller")
//掃描Api接口的包名，可多個
.setFilePath("H:/project_web/MiApiDoc")
//生成數據或讀取舊數據的文件路徑
.setDefaultGroup("默認分組")
//默認分組，不給APi分組會分配到默認分組
.create()
.run()
上面代碼找到地方一放，需要時運行一下就生成了。
註解介紹
@MiDocGroup
分組註解，一般註解在Controller類上面，該註解會讀取RequestMapping、GetMapping、PostMapping等一下註解的參數
annotation class MiDocGroup(
val group:String,//分組名稱
val rootUrl:String="",//該分組下的所有api的公共url，如果有值將會被加入到api裏
val isAnnotationMappingUrl:Boolean=true,//是否自動獲取Mapping註解的路徑,true如果rootUrl參數則自動取獲取註解
val createUser:String="",//創建用戶
val directory:String="",//分組目錄
val header: MiDocApiHeader = MiDocApiHeader()//請求時頭部所帶參數,將會下發給所有該分組下的Api
)
@MiDocApi
接口註解，一般註解在Controller類下面的函數接口上，該註解會讀取RequestMapping、GetMapping、PostMapping等一下註解的參數，讀取接口函數接收參數的數據等等
annotation class MiDocApi(
val title:String,//api標題說明
val isUseGroupConfig:Boolean=true,//是否使用分組下發的配置信息
val isAnnotationMappingUrl:Boolean=true,//是否自動獲取Mapping註解的路徑,true如果rootUrl參數則自動取獲取註解
val url:String="",//api請求url,如果沒有值，則自動獲取方法的註解的值（PostMapping、GetMapping）,如果MiDocGroup也有該值，則相加
val type:String="",//api請求方式，如果沒有值，則自動獲取方法的註解（PostMapping、GetMapping）
val remarks:String="",//api說明
val resultExample:String="",//api請求結果實例
val createUser:String="",//創建人，如果不填寫，則默認使用如果MiDocGroup.createUser
val group:String="",//api分組
val header: MiDocApiHeader = MiDocApiHeader(),//請求時頭部所帶參數
val isAutoAnnotationBody:Boolean=true,//是否自動從函數註解body參數，如果自動註解，參數fill自動默認爲true
val body: MiDocApiBody = MiDocApiBody(),//請求時所攜帶的body參數，如果'isAutoAnnotationBody=true'自動註解參數，則合併
val bodyClass: KClass<*> = Unit::class,//請求參數實體類,如果該類存在則body、isAutoAnnotationBody參數則無效
val bodyClassAllParam:Boolean=true//參數實體類所有公共變量作爲body參數，如果爲false,則只保存@MiDocParam的參數
)
@MiDocParam
接口參數註解，如果函數接收一些常量參數，該註解可以設置參數的備註等等
annotation class MiDocParam(
val remarks:String="",//字段解釋
val fill:Boolean=true,//是否必填
val exampleValue:String=""//實例值
)
下面是完整Spring Boot的一個實例，包括註解
Controller類註解實例
@RequestMapping("/api/user")
@MiDocGroup(
group = "用戶相關",//聲明一個叫‘用戶相關’的分組
header = MiDocApiHeader( MiDocApiParameter("token","String")),//該分組下的所有Api都會集成該header參數，可在@MiDocApi配置不接受
directory = "用戶端",//目錄是‘用戶端’
createUser = "小熊貓")//該分組創建人是‘小熊貓’，會分發給該分組的所有Api接口，可在@MiDocApi配置不接受
class UserController{
@PostMapping("/login")//普通SpringBoot申明一個Post請求的接口函數
@MiDocApi(
title = "用戶登錄",//該Api接口叫做‘用戶登錄’
bodyClassAllParam = true//自動讀取accout、password、type左右Body參數
)
fun login(account:String,passwd:String,type:Int):String {
//裏面自己的邏輯代碼
}
@PostMapping("/add")
@MiDocApi(
title = "添加用戶",
url = "/add",//api接口是/add如果不寫，則自動獲取PostMapping的註解值
bodyClass = UserModel::class//該參數表示直接讀取UserModel裏面的變量作爲參數
)
fun addUser(request: HttpServletRequest, @RequestBody json:JSONObject):String{
//自己的邏輯
}
/*** 其實還有很多用法，大家可以自己試試看 ****/
}
生成文檔
class TestMain {
companion object {
@JvmStatic
fun main(args: Array<String>) {
MiApiDoc.Builder()
.setDirectory(MiApiDocDirectory("用戶端","user.json",newApiSignTime = 172800))
.setDefaultHostUrl("http://192.168.3.5:9096/")
.setScanningPackages("top.mish.mxsh.Controller")
.setFilePath("H:/project_web/MiApiDoc")
.setDefaultGroup("默認分組")
.create()
.run()
}
}
}
其實還有很多用法，大家可以自己試試看,有問題的可以留言或私信，發現bug麻煩立即反饋，該項目會一直更新維護的！