一、导语
在日常web开发中，接口文档的撰写和维护必不可少。开发人员日常面对的挑战就是撰写接口文档的耗时及维护更新的费心费力。本文介绍一种通过对代码的抽象语法树AST解析，来从代码本身获取接口的定义从而渲染出接口文档；再配合git的分支管理和webhook来实现随着代码的变更更新文档及按照git的分支维护历史版本的文档，并订阅文档的变化。此外基于获取到的文档元数据可为前端代码结构体自动生成、安全扫描、测试代码等提供自动对接能力。
二、通过抽象语法树AST解析代码获取接口定义
本节以java代码为例介绍解析AST的核心原理，如下图所示。
原理示意图如上图所示，对于写好的原始java代码，从其对应的AST中获取包名 类名 字段名组合的同项目内全局唯一的标识，附加业务信息(如类型、注解、注释等)记录到数据库。接口查看的时候按照同项目、同包、同类的父子关系检索出一个接口涉及的所有信息，渲染出如下所示的接口文档。
平台展示图这样开发人员只需安心写代码和维护代码中的注解注释等辅助说明信息，接口文档即会随着代码的变更更新，无需专门抽出经历撰写和维护接口文档了。
三、通过git webhook获取代码变更和版本维护
上一节介绍了核心原理，本节介绍下业务实现。现在代码托管使用git比较多，git提供了webhook能力，通过webhook能力可以及时获取到代码的提交及变更的代码。开发人员提交代码后，文档平台获取到变更的文件，通过获取代码文件的AST更新数据库中的记录，即实现了接口文档的及时更新。具体流程如下：
流程示意图四、扩展
基于获取到的文档元数据，还可进行如下扩展。
- 主动提醒文档的变更信息，让对接方及时了解变更；
- 提供mock服务，可先定义接口契约即可联调；
- 接口版本间差异对比，直观了解变化；
- 对接测试用例平台，提供契约，减少测试人员重复输入；
- 前端等类sdk生成，减少开发人员手动录入请求和响应接口的时间。
欢迎沟通交流。
