問(wèn)題

在前不久博主發(fā)布的《Spring Boot集成Smart-Doc示例，徹底告別SpringDoc OpenAPI的代碼侵入！》，給大家演示了如何快速的在Spring Boot 中集成Smart-Doc，有小伙伴問(wèn)了我自己的項(xiàng)目都是多模塊或者微服務(wù)的，那么如何配置Smart-Doc？

針對(duì)這個(gè)問(wèn)題，博主特意給小伙伴進(jìn)行本次Spring Boot多模塊整合Smart-Doc實(shí)戰(zhàn)，這也正是很多企業(yè)在“后端 API 網(wǎng)關(guān)服務(wù) + 前端 API 網(wǎng)關(guān)服務(wù)（或管理端/用戶(hù)端分離）”多模塊架構(gòu)下經(jīng)常遇到的情況。

Smart-Doc 雖然是靜態(tài)源碼分析工具，但完全可以?xún)?yōu)雅地應(yīng)對(duì)這種 多可運(yùn)行模塊 結(jié)構(gòu)，只要理解它的生成機(jī)制，就很容易實(shí)現(xiàn)多模塊的整合！

場(chǎng)景背景

我們接著借用上一篇的項(xiàng)目改造一下，分別設(shè)置 common通用模塊（放置實(shí)體類(lèi)）、backend-api模塊（作為可啟動(dòng)的后臺(tái)管理端接口服務(wù)） 、frontend-api模塊（作為可啟動(dòng)前端用戶(hù)端接口服務(wù)），改造后的整體項(xiàng)目結(jié)構(gòu)如下：

SpringBoot 多模塊項(xiàng)目中的配置，我們這里就不贅述了，后端API服務(wù)8081端口，前端API服務(wù)8082端口

各模塊獨(dú)立生成方式

這種方式實(shí)際上就是上一篇文章的實(shí)現(xiàn)方式，在各可運(yùn)行API模塊各自設(shè)置對(duì)應(yīng)的 api-doc.json

唯一需要注意的是通用模塊作為實(shí)體類(lèi)，我們需要加以配置

后端API服務(wù)Smart-Doc配置

如博主的項(xiàng)目 backend-api/src/main/resources/smart-doc.json

{
  "projectName": "后端服務(wù) 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", //引入通用實(shí)體類(lèi)模塊
      "desc": "Common DTOs"
    }
  ]
}

前端API服務(wù)Smart-Doc配置

如博主的項(xiàng)目 backend-api/src/main/resources/smart-doc.json

{
  "projectName": "前端服務(wù) 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", //引入通用實(shí)體類(lèi)模塊
      "desc": "Common 通用實(shí)體類(lèi)模塊"
    }
  ]
}

生成文檔

使用命令行方式，進(jìn)入模塊目錄運(yùn)行

cd backend-api
mvn smart-doc:html

IDEA插件方式運(yùn)行生成

最終效果：
找到對(duì)應(yīng)文檔目錄，雙擊運(yùn)行html即可訪問(wèn)

前端API服務(wù)生成同理！

統(tǒng)一集中生成 (Makefile)

又有小伙伴要說(shuō)了，哎呀這個(gè)每個(gè)服務(wù)模塊都要去生成一次，能不能直接聚合一次性生成？ 答案是肯定的，官方也明確給出了方案：

針對(duì)多模塊的場(chǎng)景，由于構(gòu)建命令過(guò)長(zhǎng)，應(yīng)該可以放入Makefile中做編排，在自己的項(xiàng)目中新建一個(gè)Makefile文件，添加構(gòu)建命令即可。
注意：window環(huán)境下先安裝MinGW，idea中Makefile Support插件

為了驗(yàn)證是否集中生成，我們將前后端API的配置文件 smart-doc.json 中生成文檔目錄分別修改為：

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

編寫(xiě)Makefile文件

# Makefile 命令開(kāi)頭必須為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插件后，右鍵執(zhí)行該文件，最后我們看生成的效果：

至此我們就實(shí)現(xiàn)了統(tǒng)一集中生成文檔，可直接上傳到內(nèi)部文檔服務(wù)器或合并到靜態(tài)站點(diǎn)中。

總結(jié)

通過(guò)本文的介紹，相信小伙伴們已經(jīng)能掌握Spring Boot多模塊如何整合Smart-Doc了，在日常開(kāi)發(fā)過(guò)程中，我們依然還是各服務(wù)模塊獨(dú)立生成文檔即可，在 CI/CD 階段,，通過(guò)編寫(xiě)Makefile，能更快速并統(tǒng)一的集中管理生成！

至于Smart-Doc配置文件中更多的參數(shù)應(yīng)用，請(qǐng)小伙伴們參考官方文檔！

到此這篇關(guān)于Spring Boot多模塊(雙后端服務(wù))整合Smart-Doc實(shí)戰(zhàn)指南的文章就介紹到這了,更多相關(guān)Spring Boot整合Smart-Doc內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論