在微服务架构盛行的今天，Spring Boot多模块项目已成为企业级应用开发的常见形态。当系统拆分为管理端后端服务与用户端后端服务时，如何高效生成统一且规范的API文档成为技术团队的核心诉求。Smart-Doc作为一款基于源码分析的零注解文档生成工具，通过其独特的模块化支持能力，为多服务架构提供了优雅的解决方案。

一、多模块架构下的文档生成挑战

传统单模块项目使用Smart-Doc时，只需在 pom.xml中配置插件并编写 smart-doc.json配置文件即可。但在双后端服务架构中，管理端服务（8081端口）与用户端服务（8082端口）需要分别维护独立的文档生成配置，同时共享基础实体类模块。这种结构要求文档工具既能识别模块边界，又能处理跨模块依赖。

典型项目结构示例：

1smart-doc-demo/2├── common/          # 共享实体类模块3│   └── src/main/java/com/demo/common/dto/UserDTO.java4├── backend-api/     # 管理端服务5│   └── src/main/java/com/demo/backend/controller/AdminController.java6└── frontend-api/    # 用户端服务7    └── src/main/java/com/demo/frontend/controller/UserController.java

二、分模块配置实践

1. 管理端服务配置

在 backend-api/pom.xml中添加Smart-Doc插件：

xml1<plugin>2 <"www.shenyang.gov.cn.mftxty.cn"> <"www.jinzhou.gov.cn.mftxty.cn"><"www.langfang.gov.cn.mftxty.cn">  <groupId>com.github.shalousun</groupId>3    <artifactId>smart-doc-maven-plugin</artifactId>4    <version>2.6.4</version>5    <configuration>6        <configFile>${basedir}/src/main/resources/smart-doc.json</configFile>7    </configuration>8</plugin>

创建 backend-api/src/main/resources/smart-doc.json：

json1{2  "projectName": "管理端服务API",3  "outPath": "../docs/backend",4  "serverUrl": "http://localhost:8081",5  "packageFilters": "com.demo.backend.controller.*",6  "sourceCodePaths": [7    {"path": "src/main/java", "desc": "管理端模块"},8    {"path": "../common/src/main/java", "desc": "共享实体类"}9  ]10}

2. 用户端服务配置

用户端服务配置类似，关键区别在于端口和包过滤：

json1{2  "projectName": "用户端服务API",3  <"www.yingkou.gov.cn.mftxty.cn">"outPath": "<"www.changchun.gov.cn.mftxty.cn">../docs/frontend",4  "serverUrl": "http://localhost:8082",5  "packageFilters": "com.demo.frontend.controller.*",6  "sourceCodePaths": [7    {"path": "src/main/java", "desc": "用户端模块"},8    {"path": "../common/src/main/java", "desc": "共享实体类"}9  ]10}

三、跨模块依赖处理技巧

当 UserController需要使用 common模块的 UserDTO时，Smart-Doc通过 sourceCodePaths配置自动解析跨模块依赖。示例控制器代码：

java1@RestController2<"www.haerbin.gov.cn.mftxty.cn">@RequestMapping("/api/user")<"www.kunming.gov.cn.mftxty.cn">3public class UserController {4    5    @GetMapping("/{id}")6    public Result<UserDTO> getUser(@PathVariable Long id) {7        // 业务逻辑8    }9}

关键点：

1. 在 sourceCodePaths中显式声明 common模块路径
2. 确保 UserDTO<"www.dalian.gov.cn.mftxty.cn">类包含标准JavaDoc注释：

java1/**2 * 用户基础信息3 * @author Demo Team4 */5public class UserDTO implements Serializable {6    /** 用户ID */7    private Long id;8    /** 用户名 */9    private String username;10    // getters/setters...11}

四、统一文档生成方案

1. Makefile集中管理

创建项目根目录下的 Makefile：

makefile1.PHONY: generate-docs23generate-docs:4<"www.shijiazhuang.gov.cn.mftxty.cn"> <"www.quanzhou.gov.cn.mftxty.cn">   mvn clean5    mvn smart-doc:html -Dfile.encoding=UTF-8 -pl :backend-api -am6    mvn smart-doc:html -Dfile.encoding=UTF-8 -pl :frontend-api -am7    @echo "文档生成完成，输出至docs目录"

执行 make generate-docs即可一次性生成两个服务的文档。

2. 文档合并策略

对于需要统一展示的场景，可通过以下方式合并：

1. 生成单独文档后手动合并
2. 使用Smart-Doc的 allInOne配置生成综合文档：

json1{2  "allInOne": true,3  "outPath": "../docs/all",4  "coverOld": true5}

五、进阶功能实现

1. 调试页面集成

在配置文件中启用调试功能：

json1{2  "createDebugPage": true,3 <"www.tieling.gov.cn.mftxty.cn"><"www.nanning.gov.cn.mftxty.cn"><"www.panjin.gov.cn.mftxty.cn"> "requestHeaders": [4    {5      "name": "Authorization",6      "type": "string",7      "desc": "JWT令牌",8      "value": "Bearer xxx",9      "required": true10    }11  ]12}

生成后访问 http://localhost:8081/doc/debug.html即可进行接口测试。

2. 与Torna文档系统集成

配置推送至Torna的参数：

json1{2  "tornaEnable": true,3  "appKey": "your-app-key",4  "appToken": "your-app-token",5  "openUrl": "http://torna-server:7700/api"6}

执行 mvn smart-doc:torna即可将文档推送至Torna平台。

六、最佳实践建议

1. 版本控制：将 smart-doc.json纳入版本管理
2. CI/CD集成：在构建流水线中添加文档生成步骤
3. 注释规范：制定统一的JavaDoc编写规范
4. 模块隔离：每个服务模块维护独立的配置文件
5. 性能优化：通过 excludes<"www.taiyuan.gov.cn.mftxty.cn">配置排除不必要的依赖分析

七、效果对比分析

在某金融系统改造项目中，采用Smart-Doc后文档生成时间从12分钟缩短至3分钟，且消除了200余处注解维护点。

八、总结与展望

Smart-Doc通过其独特的源码分析机制，为Spring Boot多模块架构提供了高效、零侵入的文档解决方案。在实际项目中，建议采用"分模块配置+集中生成"的策略，既保持各服务的独立性，又实现文档的统一管理。随着Smart-Doc对OpenAPI 3.0支持的完善，未来在跨语言文档生成方面将有更大想象空间。

技术团队在实施过程中，应重点关注跨模块依赖的显式声明、注释规范的统一制定，以及与现有CI/CD流程的深度集成。这些实践将帮助团队在保持代码整洁的同时，大幅提升API文档的质量和维护效率。