java 开发，根据代码自动生成 api 接口文档工具，支持 RESTful 风格，今天我们来学一下 api-doc 的生成
作者：互联网编程。https://www.jianshu.com/u/4ea…
预览
在线预览地址
http://lovepeng.gitee.io/apidoc
开发原理
这个工具是一个典型的前后端分离开发的项目，想了解前后端分离开发的同学也可以下载本项目学习。
项目后端使用 java 代码，前端使用 angular 开发。Java 开发时，使用注解把文档相关信息标注在类的方法上，通过工具自动扫描代码的注解，生成 json 数据，发给前端，前端 angular 解析生成页面
本项目自带一个 spring-boot 框架为基础的 demo（这里使用 spring-boot 做演示的 demo 仅仅是为了方便，本质上只要是 java 写的项目都可以用该工具），前端用 angular 做了一个比较漂亮的界面（最终前端界面都编译成了 html，如果你前端不熟悉，可以跳过，不用管他），这里使用 angular 开发仅仅是我比较喜欢，你可以用任何你喜欢的的前端框架或者仅仅使用 html 写一个漂亮的界面就可以。
后端项目开源地址：https://github.com/liepeng328/api-doc
前端开源地址：https://github.com/liepeng328/api-doc-angular
快速启动
当成一个工具类用就可以了，下载本项目，拷贝包 com.apidoc 下的代码到你的系统，然后拷贝前端 html 页面，在 static.apidoc 文件下，到你的资源文件下。即可使用使用时，后台提供两个接口，目录文档接口和某个功能的详细接口
// 生成目录接口
ApiDoc apiDoc = new GeneratorApiDoc()
.setInfo(// 设置文档基本信息
new ApiDocInfo()
.setTitle(“ 某莫系统后台管理文档 ”)
.setVersion(“1.0”)
.setDescription(“”)
)
.generator(packageName);// 指定生成哪个包下 controller 的文档
System.err.println(JsonUtil.toString(detail));
// 详细功能接口
ApiDocAction detail = new GeneratorApiDoc()
// 设置数据库连接信息，可忽略
.setDriver(driver)
.setUrl(url)
.setUserName(userName)
.setPassword(password)
.setDataBaseName(dataBaseName)
.getApiOfMethod(methodUUID);
System.err.println(JsonUtil.toString(detail));
一个详细的例子
一个详细例子如下代码，这里是 springboot/springmvc 的 controller 示例（展示两个文档，前端接口和后台接口）参考代码这个类 UserController.java
注解详细介绍
共有 6 个注解，标注出整个文档信息（我为什么讲那么详细，那么啰嗦，而且我没有把这个项目打成 jar 包直接给别人使用，就是因为文档生成最大可能是需要特殊定制，确保你拿到该代码可以个性化定制功能，随意修改）。
Api 标注文档的功能模块
ApiAction 标注一个功能
ApiReqAparams 请求参数
ApiResqAparams 响应参数
ApiParam 参数，用以组成请求参数和响应参数
Table 用以标注实体类（比如 bean）和数据库表的关系，自动从数据库读取相关信息，不用写大量的 ApiReqAparams 和 ApiResqAparams
详细介绍如下
Api：写在类上，表明一个功能模块。属性：
name 模块名称
mapping url 映射
ApiAction：写在方法上，表明一个功能点属性：
name 方法的功能名称
mapping url 映射
description 描述
method 请求方式（get，post，put，delete）
ApiReqParams：请求参数属性：
type：参数类型
header 在请求头
url 在 url 后拼接
form 表单数据
json json 格式
ApiParam : 参数列表
value : class 类，增加该类可自动读取数据库信息，避免写多个属性
remove：配合 value 使用，去除 class 类中无用的属性，比如 id
dataType: 数据类型（字符串 string, 数字 number, 文件 file, 日期 date, 对象 object, 数组 array, 布尔类型 boolean）
descrption: 描述
defaultValue：默认值
required：是否必须
object：从属于哪个对象（因为请求参数或者响应参数可能是对象中嵌套对象的，这里为了更好的表示这种层级关系，增加两个属性，object 和 belongTo，构建一个树结构，表示对象之间无限、互相嵌套）
belognTo：对应 object 默认值为 ”0″，字符串 0
ApiRespParams：响应参数属性：
ApiParam：该参数等同于请求参数中的 ApiParam，参考如上描述
下载本项目并运行
配置 jdk8 以上版本，下载代码，运行 ApidocApplication 类 main 方法即可。然后访问地址 http://localhost:8080/index.html
感谢列表
该项目为 maven 项目，引用工具请查看 pom.xml 感谢 spring-boot 感谢 @路晓磊 的工具类 hutool https://gitee.com/loolly/hutool