2 Star 13 Fork 8

smart-doc-team / spring-boot-maven-multiple-module

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
该仓库未声明开源许可证文件(LICENSE),使用请关注具体项目描述及其代码上游依赖。
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README

spring-boot-maven-multiple-module

用于smart-doc多模块项目文档生成测试

模块介绍

  • common(存放model类,被其它模块依赖使用)
  • dubbo-api(dubbo api接口层模块)
  • dubbo-provider(dubbo服务提供者,本项目可能不能启动,官方人员比较懒,仅做文档生成测试)
  • spring-boot-web(一个web测试模块,依赖common)
  • spring-boot-web2(一个web测试模块,依赖common)

Description

smart-doc-maven-plugin多模块测试例子,本项目严格按照父子级来构建一个项目, spring-boot-web和spring-boot-web2两个web都需要依赖common模块,因此如果是直接用mvn命令 在spring-boot-web或者spring-boot-web2都是不能直接编译项目的,要想单独编译某一个模块必须是使用 maven的pl操作才行。对于严格按照父子级构建的项目使用smart-doc-maven-plugin要单独生成某一个模块 也需要使用相同的操作,操作指令参考如下。

# 生成spring-boot-web的文档
mvn -X smart-doc:html -Dfile.encoding=UTF-8  -pl :spring-boot-web -am
# 生成spring-boot-web2的文档
mvn -X smart-doc:html -Dfile.encoding=UTF-8  -pl :spring-boot-web2 -am
# 生成spring-boot-web3的文档,web3依赖sub-module中的simple-api
mvn -X smart-doc:html -Dfile.encoding=UTF-8  -pl :spring-boot-web3 -am
# 生成spring-boot-web4的文档,web3依赖module2
mvn -X smart-doc:html -Dfile.encoding=UTF-8  -pl :spring-boot-web4 -am
# 生成sub-module中子模块web-test的文档
mvn -X smart-doc:html -Dfile.encoding=UTF-8  -pl :web-test -am
# dubbo文档生成测试
mvn -X smart-doc:rpc-html -Dfile.encoding=UTF-8  -pl :dubbo-provider -am
  • -X参数是用于生成时打印插件的日志,排查问题可以使用此参数。 生成后到各模块的static中查看文档。

从本demo测试开启debug日志发现smart-doc是完全能够支持多层级依赖查找的。当然项目需要严格按照依赖传递

Makefile编排构建

上面采用了纯mvn命令去构建了maven多模块项目(maven多模块项目是不能从子模块中直接点击smart-doc插件来生成,会导致代码扫描出现问题)。 如果习惯本地开发构建文档的同学,就需要每次输入,因此这里建议使用Makefile去制作一个maven构建的编排文件。对于windows系统环境, 需要做如下操作来支持makefile(mac系统或者linux系统都原生支持):

  • window环境下先安装MinGW
  • idea中安装Makefile Support插件

安装好环境之后即可在idea中打开makefile,然后直接选中具体的构建指令运行了。

构建日志观察

在smart-doc的多模块生成中,很多初学者会遇到很多问题,生成文档缺乏注释等。我们都知道smart-doc是依赖源码的。 一定要让smart-doc加载到源码。这里一下面这条命令的执行来说面下:

mvn -X smart-doc:html -Dfile.encoding=UTF-8  -pl :spring-boot-web -am
  • 从根目执行命令表示指定生成spring-boot-web模块的命令。
  • 执行生成该模块文档过程smart-doc会调用maven的编译,然后自动将spring-boot-web依赖的common也编译。
  • smart-doc也是利用maven api来查找依赖关系的。如果编译可以成功,则smart-doc插件就能够自动加载到common模块源代码。
[INFO] API documentation is output to src/main/resources/static/doc
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary for multiple-module 1.0-SNAPSHOT:
[INFO]
[INFO] multiple-module .................................... SUCCESS [  1.133 s]
[INFO] common ............................................. SUCCESS [  1.831 s]
[INFO] spring-boot-web .................................... SUCCESS [  7.094 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  11.124 s
[INFO] Finished at: 2021-06-25T22:51:24+08:00
[INFO] ------------------------------------------------------------------------

其实从上面这个构建输出就可以发现构建生成spring-boot-web模块的过程中会自动去编译依赖的common。 因此如果你项目本身用maven命令不能自动编译依赖的模块,那说明你的项目不太符合maven父子级项目规范, common被视作独立的模块。这种情况就需要自己去处理common模块生成源码jar。否则可能无法提取注释

对于smart-doc-maven-plugin 2.2.1以前的版本如果加上-X参数,构建文档时会输出类似下面的日志。如果更高的版本则默认就会产生下面的日志。

[INFO] Smart-doc Start preparing sources at: 2021-06-26 00:20:13
[INFO] Artifacts that the current project depends on: ["org.springframework:spring-context","jakarta.annotation:jakarta.annotation-api","org.springframework:spring-core","org.spring
framework:spring-jcl","org.glassfish:jakarta.el","com.power.test:common","com.github.shalousun:common-util","com.squareup.okhttp3:okhttp","com.squareup.okio:okio"]
[INFO] Smart-doc has loaded the source code path: [{"path":"D:/workstation/spring-boot-maven-multiple-module/common//src/main/java"},{"path":"D:/workstation/
spring-boot-maven-multiple-module/spring-boot-web/src/main/java"}]
[INFO] Smart-doc Starting Create API Documentation at: 2021-06-26 00:20:15
[INFO] API documentation is output to src/main/resources/static/doc

日志中有两个重点项:

  • Artifacts that the current project depends on: 表示打印你当前构建文档的模块的pom中依赖;
  • Smart-doc has loaded the source code path: 表示smart-doc插件生成稳定中自动加载到本项目的那些源代码, 这个对于多模块项目的构建非常重要。实例中的打印就说明了构建spring-boot-web模块时插件自动加载了本项目中的common模块代码;

空文件

简介

smart-doc官方maven 插件多模块使用示例 展开 收起
Java 等 3 种语言
取消

发行版

暂无发行版

贡献者

全部

近期动态

加载更多
不能加载更多了
1
https://gitee.com/smart-doc-team/spring-boot-maven-multiple-module.git
git@gitee.com:smart-doc-team/spring-boot-maven-multiple-module.git
smart-doc-team
spring-boot-maven-multiple-module
spring-boot-maven-multiple-module
master

搜索帮助

14c37bed 8189591 565d56ea 8189591