README.md · smart-doc-team/spring-boot-maven-multiple-module

# 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-team/spring-boot-maven-multiple-module

简介

发行版

贡献者

语言

近期动态

smart-doc-team/spring-boot-maven-multiple-module .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

语言

近期动态

搜索帮助

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