api文档自动生成工具

此版本为第一版,已经废弃,建议看我的第二版本,无注解生成api文档https://github.com/liupeng328/java-api-doc

别问我比swagger好在哪里,无代码入侵,无注释,无注解都能生成文档

这里只是我写文档的一个笔记工具,我发现被google收录了,好多人通过这个看到我分享的代码,反而github无人问津,悲哀

以下是文章原文

api-doc

java开发,根据代码自动生成api接口文档工具,支持RESTful风格

预览

基本信息

演示

数据模拟mock

在线预览地址

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

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 148,637评论 1 318
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 63,443评论 1 266
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 99,164评论 0 218
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 42,075评论 0 188
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 50,080评论 1 266
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 39,365评论 1 184
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 30,901评论 2 283
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 29,649评论 0 176
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 33,122评论 0 223
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 29,734评论 2 225
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 31,093评论 1 236
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 27,548评论 2 222
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 32,028评论 3 216
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 25,765评论 0 9
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 26,291评论 0 178
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 34,162评论 2 239
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 34,293评论 2 242

推荐阅读更多精彩内容