JApiDocs 动态生成接口文档,并解析java 源码中的注释

痞子三分冷 提交于 2020-08-10 20:08:30

最近碰到一个有趣的开源项目: JApiDocs 地址:https://gitee.com/yeguozhong/JApiDocs

1、介绍

JApiDocs 是一个符合 Java 编程习惯的 Api 文档生成工具。最大程度地利用 Java 的语法特性,你只管用心设计好接口,添加必要的注释,JApiDocs 会帮你导出一份漂亮的 Html 文档,并生成相关的 Java 和 Object-C 相关数据模型代码,从此,Android 和 IOS 的同学可以少敲很多代码了,你也不需要费力维护接口文档的变化,只需要维护好你的代码就可以了。

实际使用中,你的原先代码,可能如下:

/**
 * Get User List
 * @param listForm
 */
@RequestMapping(path = "list", method = {RequestMethod.GET,  RequestMethod.POST}  )
public ApiResult<PageResult<UserVO>> list(UserListForm listForm){
    return null;
}

此时,你的代码不用改动 (仅仅需要引入依赖jar,和简单的配置),不用像swagger一样额外通过注解的形式,来给该接口添加说明,该JApiDocs会自行给该接口添加接口说明和字段说明。

换言之,该 JApiDocs 会读取源码,并解析。

2、疑问

那么,问题来了,class字节码是没有注释信息的,JApiDocs 又是怎么做到的?

3、解答

查阅readme,并 clone 出项目后,得到解释如下:

  1. 接口对象在源码中 我们知道,经过编译后的 class 字节码中是没有注释信息的,如果要通过反射字节码的方式来实现,则不可避免要引入运行时注解,这样会增加使用成本, 考虑到这一点,JApiDocs 从第二个版本之后就改成了使用解析源码的方式,而不是反射字节码的思路来实现了,但这样直接导致的缺陷就是: 所有的 Form Bean (表单)对象和返回对象就必须在项目的源码中,否则就无法解析了,如果你们项目的JavaBean对象是通过jar包的形式提供的, 那很遗憾,JApiDocs将无法支持。
易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!