使用smart-doc+torna 构建企业内部API文档与调试平台

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文档展示与在线联调能力。

经过昨天的验证，基本可用完成我们的需求。

Torna 

新建标签页 (smart-doc-group.github.io)

4.初步验证结果

4.1验证配置：

4.2源码中引入的插件配置：

 

4.3运行的结果

 

整体基本满足我们的要求，下一步将规范化编码规范，让APIDOC更可用。