Watch Star Fork

大括号 / api-docJava

加入码云
与超过 200 万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
Java 开发 ,自动生成api文档工具类 http://lovepeng.gitee.io/apidoc
克隆/下载
README.md 8.28 KB

api-doc  文档生成工具

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

预览版 http://lovepeng.gitee.io/apidoc

该工具的优势

一个简单的优势是自动生成一个api接口文档,方便维护和减少时间成本;

最大的优势在于后台程序员的自我检查和规范,写完代码后可以直接测试该接口(该工具带有mock功能,不需要开启postman等 测试工具,同理前端也不需要多开一个接口测试软件),尤其是公司团队合作,接口编写过程一般是这样的,先写接口,写完后根据接口写文档(直接注解到类文件上),然后访问文档,测试刚刚写的接口。测试通过该接口肯定就不会有问题了,如果你参与过团队开发,就会深有体会,团队制定的规范时间长了不一定每个人都遵守,直接导致垃圾代码大量存在,swagger等类似的接口文档其实最大的好处就是可以维护规范。保证接口风格的一致,使每个人写的代码都像一个人写出来的一样。

Github开源地址: https://github.com/liupeng328/api-doc
开源中国地址: https://gitee.com/lovepeng/api-doc

预览

基本信息 演示 数据模拟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

后端数据说明在这里 src/main/resources/doc/数据说明.json

功能目录对应关系

请求参数和响应参数对应

快速启动

当成一个工具类用就可以了,下载本项目,拷贝包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(apiDoc));

//详细功能接口
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以上版本,下载代码,在mysql数据库创建一个user表, sql在这里 src/main/resources/db/sql.sql 运行ApidocApplication类main方法即可 然后访问地址 http://localhost:8080/index.html

欢迎加入开发

提交bug,讨论问题,提出建议 https://github.com/liepeng328/api-doc/issues/new 参与代码修改或者文档修改,请fork本项目,然后提交pull request,这是0.0.1版,争取做到比swagger好用,尤其对国内开发者友好 欢迎各种建议,请提交issues

感谢列表

该项目为maven项目,引用工具请查看 pom.xml

感谢 spring-boot

感谢@路晓磊 的工具类hutool

感谢阿里fastjson

感谢阿里angular版前端开源框架ng-zorro

欢迎加入群交流

点击链接加入群聊【web开发交流群 317896269】:https://jq.qq.com/?_wv=1027&k=55PiekD

项目点评 ( 11 )

你可以在登录后,发表评论

8_float_left_people 8_float_left_close