一直以来,编写接口文档都是个体力活,市面上也有开源的很多文档自动生成工具,但用起来都不够顺心,社区也不活跃。
- 大名鼎鼎的Swagger,需要引入依赖包,引入全新的一套注解,并且只支持http形式的接口。
- 非侵入式的,使用Javadoc作为解决方案的开源项目有很多,但都不活跃,支持的功能也各有侧重。
所以,是时候重新造轮子了。我们期望的文档解析模型如下:
整个过程被分为了两个独立部分:元数据采集,元数据呈现,无疑增强了扩展性。
首先,使用各类客户端插件,获得关注接口的元数据,这份元数据包含类的所有信息,包含类、方法、请求参数、相应参数、注解,注释(文档注释+单行多行注释)等,有了元数据,再为特定的输出方做适配。
元数据本身也具备一定价值,它不止可以用来生成文档,也可以做其它用途,比如支撑自动化测试等。
1. 元数据采集
对于元数据采集,希望用最简单的方式,采集到足够全的元数据,不同的采集方式罗列如下。
采集方式 | 范围锁定方式 | 原理 | 特点 |
---|---|---|---|
Maven插件 | pom中参数配置 | Javadoc解析、硬解析行注释 | 适合批量更新文档,可以考虑与CICD集成 |
IDEA插件/Eclipse插件 | 鼠标选中的类、方法 | IDE提供的API,硬解析行注释 | 适合单个文件处理,更灵活 |
扫描范围的确认
默认情况下,插件应自动扫描被@Controller
或@RestController
注解的类。
支持增加特定的注解,父类、父接口、包,以扩大扫描范围。
支持排除特定的注解、类/接口、包,以减少扫描范围。
注释获取
尝试收集所有文档注释、以及部分非文档注释。
对于没有注释的类、方法、属性,尝试调用在线翻译的api翻译为中文。
2. 元数据持久化
这是个可选项,没有数据库,可以让处理速度更快,也更加轻量级。
3. 根据元数据生成文档
生成文档时,增加对javax.validation的支持(支持扩展其它第三方注解),即对@NotNull
等注解的解析反应到文档上。
对接yapi上传文档时,可以选择覆盖或更新两种策略;通过接口名称前缀,确认当前yapi上是否已存在某个接口。
默认情况下,一个类对应对应yapi中的一个分类,若果该类中只有一个public方法,则不再增加分类,直接将接口添加到根目录。
4. 小结
本文简单介绍了对于文档自动化的需求,满足该需求的文档生成工具,应当会比较好用。