MateCloud API文档：Smart-Doc替代Swagger的完整方案指南

MateCloud API文档Smart-Doc替代Swagger的完整方案指南【免费下载链接】matecloudMateCloud是一款基于Spring Cloud Alibaba的微服务架构。目前已经整合Spring Boot 4.0.7、 SpringCloud 2025、Spring Cloud Alibaba 2025、Spring Security Oauth2、Feign、Dubbo、JetCache、RocketMQ等支持多租户的低代码平台Saas平台开发套件项目地址: https://gitcode.com/GitHub_Trending/ma/matecloud在微服务架构中MateCloud API文档的生成和管理至关重要。传统的Swagger方案虽然流行但存在运行时依赖、代码污染等问题。MateCloud选择了Smart-Doc作为其API文档解决方案提供了一种更优雅、更高效的文档生成方式。本文将详细介绍如何在MateCloud项目中配置和使用Smart-Doc以及为什么它比Swagger更适合DDD微服务架构。为什么选择Smart-Doc替代SwaggerSmart-Doc的核心优势 Smart-Doc是一个基于Java源代码和Javadoc注释的API文档生成工具与Swagger相比具有以下显著优势零运行时依赖Smart-Doc在编译时生成文档不需要在运行时加载任何注解或依赖代码零污染不需要在业务代码中添加任何Swagger注解保持代码的纯净性更好的DDD支持完全符合MateCloud的DDD架构理念不侵入领域层多格式输出支持HTML、Markdown、Postman等多种格式Dubbo RPC支持能够为Dubbo接口生成完整的RPC文档MateCloud的文档策略 MateCloud项目采用分层配置策略通过mate-doc-starter模块统一管理API文档生成matecloud/ ├── docs/smart-doc-template.json # 全局配置模板 ├── mate-starters/mate-doc-starter/ # 文档starter模块 │ ├── src/main/java/vip/mate/starter/doc/ │ │ ├── config/ │ │ │ ├── SmartDocAutoConfiguration.java │ │ │ └── SmartDocProperties.java │ │ └── resources/ │ │ └── smart-doc-config-template.json └── 各业务模块的resources/smart-doc.json # 模块级配置快速开始5分钟配置Smart-Doc1. 添加依赖配置在项目的pom.xml中Smart-Doc已经预配置好!-- 根pom.xml中的版本管理 -- smart-doc.version3.0.9/smart-doc.version smart-doc-maven-plugin.version3.0.9/smart-doc-maven-plugin.version !-- 各业务模块的pom.xml -- build plugins plugin groupIdcom.ly.smart-doc/groupId artifactIdsmart-doc-maven-plugin/artifactId configuration configFile./src/main/resources/smart-doc.json/configFile /configuration /plugin /plugins /build2. 配置Smart-Doc配置文件每个业务模块都需要一个smart-doc.json配置文件。以mate-system模块为例{ serverUrl: http://localhost:9030, isStrict: false, allInOne: true, outPath: ./target/smart-doc, projectName: MateCloud System API, packageFilters: vip.mate.system.**.trigger.controller, showAuthor: true, createDebugPage: true, style: xt256, coverOld: true, requestHeaders: [ { name: Authorization, type: string, desc: Sa-Token认证令牌, required: false, since: 1.0.0 } ], responseBodyAdvice: { className: vip.mate.base.result.Result } }图MateCloud微服务架构Smart-Doc为每个服务生成独立的API文档3. 编写规范的Javadoc注释Smart-Doc通过解析Javadoc自动生成文档。以下是MateCloud推荐的注释规范/** * 角色管理API * * p路径: {code /api/v1/admin/roles} * p角色的权限集是分配给该角色的菜单权限的并集。 * 缓存在Redis中的权限列表key {code mate:user:perm:userId} * 在登录时重建 — 更改角色分配后受影响的用户必须重新登录才能看到新权限。 * * author MateCloud团队 * since 1.0.0 */ RestController RequestMapping(/api/v1/admin/roles) RequiredArgsConstructor SaCheckLogin public class RoleController { /** * 创建新角色 * * 创建一个新的系统角色并可选地分配菜单权限。 * 角色代码必须全局唯一。 * * param command 角色创建命令|required * return 创建成功的角色信息 * apiNote 需要管理员权限 * since 1.0.0 */ PostMapping SaCheckPermission(Perms.ROLE_CREATE) OperationLog(module 角色管理, operation 创建角色) public ResultRoleVO create(Valid RequestBody RoleCreateCommand command) { // 业务逻辑 } }图MateCloud系统管理界面Smart-Doc生成的API文档与此界面完全对应高级配置与最佳实践多服务文档生成MateCloud支持为多个微服务同时生成文档# 生成单个服务的文档 cd mate-system mvn smart-doc:html # 生成多个服务的文档 mvn smart-doc:html -pl mate-auth,mate-biz/mate-system # 生成所有格式的文档 mvn compile -Pgenerate-docs -pl mate-auth,mate-biz/mate-systemDubbo RPC文档生成对于Dubbo接口Smart-Doc也能完美支持/** * 用户RPC服务 * * 通过Dubbo RPC提供用户数据检索和管理功能。 * 由mate-system实现被mate-auth和其他服务消费。 * * author MateCloud团队 * dubbo * since 1.0.0 */ public interface IRpcUserService { /** * 根据手机号查找用户 * * param mobile 11位手机号码|required * return 包含角色和权限的用户信息未找到时返回null * since 1.0.0 */ UserInfoDTO findByMobile(String mobile); }配置Dubbo文档生成{ serverUrl: dubbo://127.0.0.1:20880, isStrict: false, allInOne: true, outPath: docs/rpc, projectName: MateCloud System Service RPC API, packageFilters: vip.mate.api.service, rpcApiDependencies: [ { artifactId: mate-api, groupId: vip.mate, version: 1.0.0 } ] }CI/CD集成在GitHub Actions中自动生成文档- name: Generate API Documentation run: | mvn smart-doc:html -pl mate-auth,mate-biz/mate-system --no-transfer-progress mvn smart-doc:rpc-html -pl mate-biz/mate-system --no-transfer-progress - name: Upload API Docs Artifact uses: actions/upload-artifactv4 with: name: api-docs path: | mate-auth/docs/api/ mate-biz/mate-system/docs/api/ mate-biz/mate-system/docs/rpc/图MateCloud管理仪表板所有API都可通过Smart-Doc生成的文档进行测试Smart-Doc生成文档示例HTML文档结构生成的HTML文档包含以下部分API概览- 项目名称、版本信息端点列表- 按控制器分组的所有API详细端点信息HTTP方法 URL路径请求参数表名称、类型、必填、描述、默认值请求体JSON示例使用Javadoc中的mock值响应体JSON示例错误代码表全局请求头如satoken错误代码字典- 从ErrorCode枚举生成修订历史支持的输出格式Smart-Doc支持多种输出格式格式命令输出文件用途HTMLmvn smart-doc:htmldocs/api/index.html在线浏览Markdownmvn smart-doc:markdowndocs/api/AllInOne.md文档集成Postmanmvn smart-doc:postmandocs/api/postman.jsonAPI测试Dubbo HTMLmvn smart-doc:rpc-htmldocs/rpc/index.htmlRPC文档图MateCloud配置管理界面Smart-Doc文档帮助开发者快速理解API使用方式常见问题与解决方案问题1文档生成失败症状运行mvn smart-doc:html时出现编译错误。解决方案检查Javadoc注释是否规范确认smart-doc.json配置正确确保所有依赖模块已编译问题2缺少请求示例症状生成的文档中没有请求/响应示例。解决方案在DTO类中添加mock注解Data public class LoginCommand { /** * 用户名 * mock admin */ NotBlank private String username; /** * 密码 * mock admin123 */ NotBlank private String password; }问题3响应包装器不生效症状响应没有包装在ResultT中。解决方案在配置文件中正确设置响应包装器{ responseBodyAdvice: { className: vip.mate.base.result.Result, typeParameters: [T] } }最佳实践总结1. 注释规范 为每个Controller添加类级别Javadoc为每个方法添加详细描述和参数说明使用mock为字段提供示例值标记apiNote说明特殊注意事项使用since标记版本信息2. 配置管理 ⚙️每个服务模块维护独立的smart-doc.json使用模板减少重复配置在CI/CD中自动生成文档定期更新文档版本3. 团队协作 将API文档纳入代码审查保持文档与代码同步更新为新成员提供文档阅读指南定期进行API文档评审4. 性能优化 只在需要时生成文档使用缓存避免重复生成按模块生成减少内存占用在开发环境使用增量生成图MateCloud登录审计日志Smart-Doc文档帮助理解认证相关API进阶功能自定义扩展自定义响应示例通过responseBodyAdvice配置自定义响应包装{ responseBodyAdvice: { className: vip.mate.base.result.Result, typeParameters: [T], exclude: [ vip.mate.base.result.PageResult ] } }错误代码字典自动从枚举生成错误代码文档{ errorCodeDictionaries: [ { title: 错误代码, enumClassName: vip.mate.base.enums.ErrorCode, codeField: code, descField: message } ] }请求头配置定义全局请求头{ requestHeaders: [ { name: satoken, type: string, desc: Sa-Token认证令牌, value: , required: false, since: 1.0.0, pathPatterns: /api/**, excludePathPatterns: /api/v1/auth/login,/api/v1/auth/sms/** }, { name: X-Tenant-Id, type: string, desc: 租户ID, required: false, since: 1.0.0 } ] }结语MateCloud选择Smart-Doc作为API文档解决方案不仅因为它的零运行时依赖和代码零污染特性更因为它完美契合了DDD架构理念。通过标准的Javadoc注释开发者可以专注于业务逻辑的实现而无需担心文档维护的负担。Smart-Doc在MateCloud项目中的成功应用证明对于复杂的微服务架构基于源码分析的文档生成方案比传统的注解方案更加优雅和高效。无论是REST API还是Dubbo RPCSmart-Doc都能提供完整、准确、易读的文档大大提升了团队协作效率和API的可维护性。开始使用Smart-Doc让你的MateCloud项目API文档更加专业和规范 【免费下载链接】matecloudMateCloud是一款基于Spring Cloud Alibaba的微服务架构。目前已经整合Spring Boot 4.0.7、 SpringCloud 2025、Spring Cloud Alibaba 2025、Spring Security Oauth2、Feign、Dubbo、JetCache、RocketMQ等支持多租户的低代码平台Saas平台开发套件项目地址: https://gitcode.com/GitHub_Trending/ma/matecloud创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考