Spring Boot多模块（双后端服务）整合Smart-Doc实战，Smart-Doc 真香！

🌷 古之立大事者，不惟有超世之才，亦必有坚忍不拔之志
🎐 个人CSND主页——Micro麦可乐的博客
🐥《Docker实操教程》专栏以最新的Centos版本为基础进行Docker实操教程，入门到实战
🌺《RabbitMQ》专栏19年编写主要介绍使用JAVA开发RabbitMQ的系列教程，从基础知识到项目实战
🌸《设计模式》专栏以实际的生活场景为案例进行讲解，让大家对设计模式有一个更清晰的理解
🌛《开源项目》本专栏主要介绍目前热门的开源项目，带大家快速了解并轻松上手使用
🍎 《前端技术》专栏以实战为主介绍日常开发中前端应用的一些功能以及技巧，均附有完整的代码示例
✨《开发技巧》本专栏包含了各种系统的设计原理以及注意事项，并分享一些日常开发的功能小技巧
💕《Jenkins实战》专栏主要介绍Jenkins+Docker的实战教程，让你快速掌握项目CI/CD，是2024年最新的实战教程
🌞《Spring Boot》专栏主要介绍我们日常工作项目中经常应用到的功能以及技巧，代码样例完整
👍《Spring Security》专栏中我们将逐步深入Spring Security的各个技术细节，带你从入门到精通，全面掌握这一安全技术
如果文章能够给大家带来一定的帮助！欢迎关注、评论互动～

Spring Boot多模块（双后端服务）整合Smart-Doc实战

• 问题
  • 场景背景
• 各模块独立生成方式
  • 后端API服务Smart-Doc配置
  • 前端API服务Smart-Doc配置
  • 生成文档
• 统一集中生成 (Makefile)
• 总结

问题

在前不久博主发布的《Spring Boot集成Smart-Doc示例，彻底告别SpringDoc OpenAPI的代码侵入！》，给大家演示了如何快速的在Spring Boot 中集成Smart-Doc，有小伙伴问了我自己的项目都是多模块或者微服务的，那么如何配置Smart-Doc？

针对这个问题，博主特意给小伙伴进行本次Spring Boot多模块整合Smart-Doc实战，这也正是很多企业在“后端 API 网关服务 + 前端 API 网关服务（或管理端/用户端分离）”多模块架构下经常遇到的情况。

Smart-Doc 虽然是静态源码分析工具，但完全可以优雅地应对这种 多可运行模块 结构，只要理解它的生成机制，就很容易实现多模块的整合！

场景背景

我们接着借用上一篇的项目改造一下，分别设置common通用模块（放置实体类）、backend-api模块（作为可启动的后台管理端接口服务） 、frontend-api模块（作为可启动前端用户端接口服务），改造后的整体项目结构如下：

SpringBoot 多模块项目中的配置，我们这里就不赘述了，后端API服务8081端口，前端API服务8082端口

各模块独立生成方式

这种方式实际上就是上一篇文章的实现方式，在各可运行API模块各自设置对应的 api-doc.json

唯一需要注意的是通用模块作为实体类，我们需要加以配置

后端API服务Smart-Doc配置

如博主的项目backend-api/src/main/resources/smart-doc.json

{"projectName":"后端服务 API","allInOne":true,"outPath":"src/main/resources/static/doc","serverUrl":"http://localhost:8081","packageFilters":"com.toher.smartdocdemo.backend.controller.*","sourceCodePaths":[{"path":"src/main/java","desc":"Backend Module"},{"path":"../common/src/main/java",//引入通用实体类模块"desc":"Common DTOs"}]}

前端API服务Smart-Doc配置

如博主的项目backend-api/src/main/resources/smart-doc.json

{"projectName":"前端服务 API","outPath":"src/main/resources/static/doc","projectName":"SmartDoc Demo","allInOne":true,"serverUrl":"http://localhost:8082","packageFilters":"com.toher.smartdocdemo.frontend.controller.*","sourceCodePaths":[{"path":"src/main/java","desc":"前端API模块"},{"path":"../common-bean/src/main/java",//引入通用实体类模块"desc":"Common 通用实体类模块"}]}

生成文档

使用命令行方式，进入模块目录运行

cd backend-api mvn smart-doc:html 

IDEA插件方式运行生成

最终效果：
找到对应文档目录，双击运行html即可访问

前端API服务生成同理！

统一集中生成 (Makefile)

又有小伙伴要说了，哎呀这个每个服务模块都要去生成一次，能不能直接聚合一次性生成？ 答案是肯定的，官方也明确给出了方案：

针对多模块的场景，由于构建命令过长，应该可以放入Makefile中做编排，在自己的项目中新建一个Makefile文件，添加构建命令即可。
注意：window环境下先安装MinGW，idea中Makefile Support插件

为了验证是否集中生成，我们将前后端API的配置文件 smart-doc.json 中生成文档目录分别修改为：

#后端"outPath":"../docs/backend", #前端"outPath":"../docs/frontend", 

编写Makefile文件

# Makefile 命令开头必须为tab键 如mvn前端必须是tab键# 生成backend-api的文档 backend-api@html-doc: mvn smart-doc:html -Dfile.encoding=UTF-8 -pl :backend-api @echo "后端API文档生成完成！"# 生成frontend-api的文档 frontend-api@html-doc: mvn smart-doc:html -Dfile.encoding=UTF-8 -pl :frontend-api -am @echo "前端API文档生成完成！"

IDEA下载好Makefile Support插件后，右键执行该文件，最后我们看生成的效果：

至此我们就实现了统一集中生成文档，可直接上传到内部文档服务器或合并到静态站点中。

总结

通过本文的介绍，相信小伙伴们已经能掌握Spring Boot多模块如何整合Smart-Doc了，在日常开发过程中，我们依然还是各服务模块独立生成文档即可，在 CI/CD 阶段,，通过编写Makefile，能更快速并统一的集中管理生成！

至于Smart-Doc配置文件中更多的参数应用，请小伙伴们参考官方文档！

如果你在实践过程中有任何疑问或更好的扩展思路，欢迎在评论区留言，最后希望大家一键三连给博主一点点鼓励！