1.前言
经过近年的努力,业务平台已在多家规模企业稳定运行,团队进入了成长期。业务的扩展,平台的成熟,以前分块研发,集中整合的方式有点不太合适团队的发展。在转型早期,把团队划分为多个板块是准确的,相关的领域专家在各自的领域内快速成型,这让我们在转入java后能快速交付相对可靠的平台的原因。
2022年下半年起,核心产品基本成型,走向了全面优化过程。到目前为止,基础平台的完善优先级在逐渐降低,项目交付的速度要求在不断提升。所以,以小团队输出模式不再适合我们。我们需要一个完整而全面的支持资料,尤其是支持产品交付的API文档。
所以,近期抽时间查找了下开源可用的自动化API文档插件。
在查找过程中,很多优秀的解决方案进入到我们的眼帘。
2.我们的需求
希望有一个自动化API文档插件,在0入侵的模式下能完成API文档的构建,并能提供在线调试入口。
在项目早期我们引入过swagger,由于前期时间紧张,并未对swagger提供的注解进行标准化完善,到目前为止并未大规模构建。当下,由于平台规模的不断扩张,已无法回头再来完善相关的注解了。所以更希望有一个基于java doc 的APIDOC平台。
3.smart-doc+torna
经过一段时间的整理,smart-doc+torna组合进入了我们的视野。
smart-doc基于java 的注释信息自动完成API文档的提取,形成了APIDOC文档。
smart-doc与torna集成,把生成的文档自动推送到torna中,torna对外提供APIDoc文档展示与在线联调能力。
经过昨天的验证,基本可用完成我们的需求。
新建标签页 (smart-doc-group.github.io)
4.初步验证结果
4.1验证配置:
4.2源码中引入的插件配置:
4.3运行的结果
整体基本满足我们的要求,下一步将规范化编码规范,让APIDOC更可用。