文档自动化生成组件,有如下几个设计目标:
- 配置足够少,上手简单,默认配置能满足大部分场景
- 非侵入式,不用修改现有代码
- 方式灵活,支持批量操作和单个操作
- 代码即文档,将代码里所有的注释转化到文档里(即使是非文档注释)
1. 支持的检测范围
基于对公司现状的了解,应该至少支持如下几种扫描范围的选择方式:
- 对
@Controller
@RestController
扫描 - 对
@RpcService
扫描 - 对
XxxHandler
扫描,真实场景是使用code对http请求进行转发,每个code对应一个接口,通常它们都有一个共同的父类
因此检测范围的配置,需要非常灵活;maven插件的配置是写在pom.xml中;IDEA/Eclipse插件配置是在软件配置界面中。
2. 组件划分
3. 技术实现
接口解析:提供三种不同客户端,分别需要对接它们的API;虽然API不同,但应该保证最终的输出结果一致。
数据存储:异步将接口信息推送至远程服务进行存储。
数据输出:根据掌握的接口信息,尽可能全的向yapi写入信息;同时支持覆盖和合并两种策略。输出方式目前仅考虑yapi,markdown和json示例暂缓实现。
4.数据结构
将扫描范围的类,及这些类关联的全部信息,存储到如下数据结构中。