Spring Boot多模块(双后端服务)整合Smart-Doc实战指南_Java

问题

在前不久博主发布的《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插件后，右键执行该文件，最后我们看生成的效果：