一直以来，编写接口文档都是个体力活，市面上也有开源的很多文档自动生成工具，但用起来都不够顺心，社区也不活跃。
- 大名鼎鼎的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. 小结
本文简单介绍了对于文档自动化的需求，满足该需求的文档生成工具，应当会比较好用。
