如何快速实现spring boot技术栈api文档的生成

作为开发，写接口文档一直是一个很头痛的问题，尤其在前后端分离大量盛行的当下，后端必须要为前端同事提供明确的入参出参文档，否则整个对接工作无法顺利进行，前后端的相爱相杀的大戏时常上演。笔者刚工作的那些年，swagger都还没有正式发布，对接前端和app端的文档全靠手写markdown完成。写接口文档的时间常常感jio比写代码耗费的时间还长。随着技术的进步和众多开源人的努力，近几年针对java开发的文档生成工具越来越多。新入行的开发人员再也不用去体会过去的那些辛酸历程。在java文档生成的这个领域，swagger一直是一只领头羊。可能占据着90%的市场， 除此还有像 Spring REST Doc这些有名的工具也被大量的使用，但是这些工具在笔者看来使用比较蛮烦，侵入性高。今天笔者要给大家介绍和推荐一款本人开源的文档工具smart-doc，也会介绍如何使用这个工具来生成自己的文档。

一、当前市面上文档工具存在的问题

下面来列举当前市场上主流文档工具的问题：

• 侵入性强，需要编写大量注解，代表工具如：swagger，还有一些公司自研的文档工具
• 强依赖性，如果项目不想使用该工具，业务代码无法编译通过。
• 代码解析能力弱，使用文档不齐全，主要代表为国内众多开源的相关工具。
• 众多基于注释分析的工具无法解析jar包里面的注释(sources jar包)，需要人工配置源码路径，无法满足DevOps构建场景。
• 无法支持多模块复杂项目代码分析。

二、smart-doc如何解决上述问题

• 通过分析源码注释自动生成API文档，不用编写任何注解，秉承注释即文档的原则，并且提供注释强制检查。
• smart-doc开发了smart-doc-maven-plugin和smart-doc-gradle-plugin插件，项目仅仅依赖插件，剔除插件无修改项目不报任何编译错误。
• smart-doc在国内经过上百家企业的使用，做了很多场景的分析，解析能力很强。
• smart-doc的maven和gradle插件自动分析项目依赖，自动完成对自发布jar包和第三方jar包源码的加载，不需要指定任何源码路径。
• smart-doc的maven和gradle能够自动识别项目依赖，多模块maven和gradle项目都不是问题。
• smart-doc文档维护比较完善，码云上的wiki有20个页面介绍各种使用方式。