一直以来,编写接口文档都是个体力活,市面上也有开源的很多文档自动生成工具,但用起来都不够顺心,社区也不活跃。

  1. 大名鼎鼎的Swagger,需要引入依赖包,引入全新的一套注解,并且只支持http形式的接口。
  2. 非侵入式的,使用Javadoc作为解决方案的开源项目有很多,但都不活跃,支持的功能也各有侧重。

所以,是时候重新造轮子了。我们期望的文档解析模型如下:

autodoc1

整个过程被分为了两个独立部分:元数据采集,元数据呈现,无疑增强了扩展性。

首先,使用各类客户端插件,获得关注接口的元数据,这份元数据包含类的所有信息,包含类、方法、请求参数、相应参数、注解,注释(文档注释+单行多行注释)等,有了元数据,再为特定的输出方做适配。

元数据本身也具备一定价值,它不止可以用来生成文档,也可以做其它用途,比如支撑自动化测试等。

1. 元数据采集

对于元数据采集,希望用最简单的方式,采集到足够全的元数据,不同的采集方式罗列如下。

采集方式 范围锁定方式 原理 特点
Maven插件 pom中参数配置 Javadoc解析、硬解析行注释 适合批量更新文档,可以考虑与CICD集成
IDEA插件/Eclipse插件 鼠标选中的类、方法 IDE提供的API,硬解析行注释 适合单个文件处理,更灵活

扫描范围的确认

默认情况下,插件应自动扫描被@Controller@RestController注解的类。
支持增加特定的注解,父类、父接口、包,以扩大扫描范围。
支持排除特定的注解、类/接口、包,以减少扫描范围。

注释获取

尝试收集所有文档注释、以及部分非文档注释。
对于没有注释的类、方法、属性,尝试调用在线翻译的api翻译为中文。

2. 元数据持久化

这是个可选项,没有数据库,可以让处理速度更快,也更加轻量级。

3. 根据元数据生成文档

生成文档时,增加对javax.validation的支持(支持扩展其它第三方注解),即对@NotNull等注解的解析反应到文档上。

对接yapi上传文档时,可以选择覆盖或更新两种策略;通过接口名称前缀,确认当前yapi上是否已存在某个接口。

默认情况下,一个类对应对应yapi中的一个分类,若果该类中只有一个public方法,则不再增加分类,直接将接口添加到根目录。

4. 小结

本文简单介绍了对于文档自动化的需求,满足该需求的文档生成工具,应当会比较好用。


文章作者: 沉迷思考的鱼
版权声明: 本博客所有文章除特別声明外,均采用 CC BY 4.0 许可协议。转载请注明来源 沉迷思考的鱼 !
评论
 上一篇
文档自动化生成设计 文档自动化生成设计
文档自动化生成组件,有如下几个设计目标: 配置足够少,上手简单,默认配置能满足大部分场景 非侵入式,不用修改现有代码 方式灵活,支持批量操作和单个操作 代码即文档,将代码里所有的注释转化到文档里(即使是非文档注释) 1. 支持的检测范围
2020-06-18 沉迷思考的鱼
下一篇 
宏观调控-金融周期 宏观调控-金融周期
经济周期是一直存在的,它包括复苏,过热,滞涨和衰退。为了对冲经济周期的波动,央行这只看的见得手就得进行宏观调控,而这个宏观调控所产生的周期波动,就叫做金融周期。 它也分为四个周期,分别是紧货币宽信用,宽货币宽信用,紧货币紧信用,宽货币紧信用
2020-06-12 沉迷思考的鱼
  目录