好看的Spring项目文档生成工具-MiApiDoc(1)

前言：其实我是个开发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麻烦立即反馈，该项目会一直更新维护的！