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

问题

在前不久博主发布的《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配置文件中更多的参数应用，请小伙伴们参考官方文档！

到此这篇关于Spring Boot多模块(双后端服务)整合Smart-Doc实战指南的文章就介绍到这了,更多相关Spring Boot整合Smart-Doc内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

最新评论