1. 什么是smart-doc

smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具，smart-doc在业内率先提出基于JAVA泛型定义推导的理念，完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。你只需要按照java-doc标准编写注释， smart-doc就能帮你生成一个简易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+的文档。

2. smart-doc的功能特性

零注解、零学习成本、只需要写标准JAVA注释。
基于源代码接口定义自动推导，强大的返回结构推导。
支持Spring MVC、Spring Boot、Spring Boot Web Flux(controller书写方式)、Feign。
支持Callable、Future、CompletableFuture等异步接口返回的推导。
支持JavaBean上的JSR303参数校验规范，包括分组验证。
对JSON请求参数的接口能够自动生成模拟JSON参数。
对一些常用字段定义能够生成有效的模拟值。
支持生成JSON返回值示例。
支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。
支持生成多种格式文档：Markdown、HTML5、Asciidoctor、Postman Collection、OpenAPI 3.0。 Up- 开放文档数据，可自由实现接入文档管理系统。
支持导出错误码和定义在代码中的各种字典码到接口文档。
支持Maven、Gradle插件式轻松集成。
支持Apache Dubbo RPC接口文档生成。
debug接口调试html5页面完全支持文件上传，下载(@download tag标记下载方法)测试。

3. smart-doc自定义注释tag

tag名称	描述
@ignore	ignore tag用于过滤请求参数对象上的某个字段，设置后smart-doc不输出改字段到请求参数列表中。关于响应字段忽略的请看，如果ignore加到方法上，则接口方法不会输出到文档。从1.8.4开始ignore支持添加到controller上进行忽略不想生成文档的接口类。ignore也可以用于方法上忽略某个请求参数。
@required	如果你没有使用JSR303参数验证规范实现的方式来标注字段，就可以使用@required去标注请求参数对象的字段，标注smart-doc在输出参数列表时会设置为true。建议用JSR303
@mock	从smart-doc 1.8.0开始，mock tag用于在对象基本类型字段设置自定义文档展示值。设置值后smart-doc不再帮你生成随机值。方便可以通过smart-doc直接输出交付文档。
@dubbo	从smart-doc 1.8.7开始，dubbo tag用于在dubbo的api接口类上添加让smart-doc可以扫描到dubbo rpc的接口生成文档。
@restApi	从smart-doc 1.8.8开始，restApi tag用于支持smart-doc去扫描Spring Cloud Feign的定义接口生成文档。
@order	从smart-doc 1.9.4开始，order tag用于设置controller接口或者api入口的自定义排序序号，@order 1就表示设置序号为1。
@ignoreResponseBodyAdvice	从smart-doc 1.9.8开始，ignoreResponseBodyAdvice tag用于忽略ResponseBodyAdvice设置的包装类。
@download	从smart-doc 2.0.1开始，download tag用于标注在controller的文件下载方法上，生成debug页面时可实现文件下载测试。并且支持下载文件带请求头参数测试。
@page	从smart-doc 2.0.2开始，page tag用于标注在controller的方法上表示该方法用来渲染返回一个静态页面，生成debug页面时如果发起测试，测试页面会自动在浏览器开启新标签显示页面。
@ignoreParams	从smart-doc 2.1.0开始，ignoreParams tag用于标注在controller方法上忽略掉不想显示在文档中的参数，例如：@ignoreParams id name，多个参数名用空格隔开
@response	从smart-doc 2.2.0开始，response tag标注在controller方法上可以允许用这自己定义返回的json example。建议只在返回基础类型时使用，如：Result类型这种泛型是简单原生类型的响应。
@tag	@since 2.2.5, @tag用于将controller方法分类, 可以将不同contoller下的方法指定到多个分类下, 同时也可以直接指定controller为一个分类或多个分类

4. 通过引入依赖生成文档

4.1 pom文件中增加smart-doc的依赖（需要注意jar包的冲突问题）

<dependency><groupId>com.github.shalousun</groupId><artifactId>smart-doc</artifactId><version>2.0.5</version><scope>test</scope>
</dependency>

4.2 通过单元测试调用API方法生成

@Test
public void buildSmartDoc(){ApiConfig config = new ApiConfig();config.setStrict(true);//严格模式config.setAllInOne(true);//true则将所有接口合并到一个config.setServerUrl("http://xxxx.xxxxx.xx/wevruit/");config.setCoverOld(true);config.setOutPath("d:\\md");//输出目录// @since 1.2,如果不配置该选项，则默认匹配全部的controller,// 如果需要配置有多个controller可以使用逗号隔开config.setPackageFilters("com.xxxx.xxxxx.controller.account");//默认是src/main/java,maven项目可以不写// 生成markdown文档ApiDocBuilder.buildApiDoc(config);// 生成html文档// HtmlApiDocBuilder.buildApiDoc(config);// 生成openApi文档// OpenApiBuilder.buildOpenApi(config);
}

4.3 查看文档

5. 通过集成smart-doc的maven插件生成文档

5.1 添加maven插件（使用插件后就不需要在项目的maven dependencies中添加smart-doc的依赖了，直接使用插件即可）

<plugin><groupId>com.github.shalousun</groupId><artifactId>smart-doc-maven-plugin</artifactId><version>2.3.0</version><configuration><!--指定生成文档的使用的配置文件,配置文件放在自己的项目中--><configFile>${basedir}/src/main/resources/smart-doc.json</configFile><!--指定项目名称--><!--<projectName>测试</projectName>--><!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉--><!--<excludes>--><!--&lt;!&ndash;格式为：groupId:artifactId;参考如下&ndash;&gt;--><!--</excludes>--><!--自1.0.8版本开始，插件提供includes支持,配置了includes后插件会按照用户配置加载而不是自动加载，因此使用时需要注意--><!--smart-doc能自动分析依赖树加载所有依赖源码，原则上会影响文档构建效率，因此你可以使用includes来让插件加载你配置的组件--><includes><!--格式为：groupId:artifactId;参考如下--><!--需要加入该依赖包的源码进行解析，否则dto中的注释无法被解析（泛型中嵌套对象无法分析）--><include>groupId:artifactId</include></includes></configuration>
</plugin>

5.2 添加smart-doc生成文档的配置（配置内容实际上就是以前采用单元测试编写的ApiConfig转成json后的结果）

{"projectName": "admin-end","outPath": "../../document/接口文档/", // 生成文件输出目录--必填项"serverUrl": "https://xxxx.xxxxx.cn/", // 接口对应服务器地址,"coverOld": true, // 是否覆盖旧的文件,"allInOne": false, // 是否将文档合并到一个文件中,//"allInOneDocFileName":"admin.md", // 自定义设置输出文档名称"isStrict": false, // 是否开启严格模式"style":"xt256",// "createDebugPage": true, // 生成html时才有效"packageFilters": "com.xxx.xxx.xxxxx.xxxxxx.controller" // controller包过滤
}

5.3 在idea中或使用mvn命令生成文档

//生成html
mvn -Dfile.encoding=UTF-8 smart-doc:html
//生成markdown
mvn -Dfile.encoding=UTF-8 smart-doc:markdown
//生成adoc
mvn -Dfile.encoding=UTF-8 smart-doc:adoc
//生成postman json数据
mvn -Dfile.encoding=UTF-8 smart-doc:postman
// 生成 Open Api 3.0+,Since smart-doc-maven-plugin 1.1.5
mvn -Dfile.encoding=UTF-8 smart-doc:openapi

5.4 maven多模块中使用插件

如果maven结构是严格按照父子级来配置的，比如web1和web2都依赖于common，这种情况下如果跑到web1下或者web2目录下直接执行mvn命令来编译都是无法完成的。需要在根目录上去执行命令编译命令才能通过，而smart-doc插件会通过类加载器去加载用户配置的一些类，因此是需要调用编译的和执行命令是一样的。这种情况下建议你建smart-doc-maven-plugin放到根pom中，在web1和web2中放置各自的smart-doc.json配置。然后通过-pl去指定让smart-doc生成指定
模块的文档。操作命令如下：

# 生成web1模块的api文档
mvn smart-doc:markdown -Dfile.encoding=UTF-8  -pl :web1 -am
# 生成web2模块的api文档
mvn smart-doc:markdown -Dfile.encoding=UTF-8  -pl :web2 -am

6. 生成Postman json文件与导入Postman测试

6.1 调整smart-doc配置

{"projectName": "admin-end","outPath": "../../document/接口文档/", // 生成文件输出目录--必填项"serverUrl": "https://{{server}}/", //导出postman建议将server设置成这样，然后在postman中建立一个server环境变量，调试时只需根据实际服务器来修改server的值。"coverOld": true, // 是否覆盖旧的文件,"allInOne": true, // 是否将文档合并到一个文件中,//"allInOneDocFileName":"admin.md", // 自定义设置输出文档名称"isStrict": false, // 是否开启严格模式"style":"xt256",// "createDebugPage": true, // 生成html时才有效"packageFilters": "com.xxx.xxx.xxxxx.xxxxxx.controller" // controller包过滤
}

6.2 导出postman json文件

mvn smart-doc:postman -Dfile.encoding=UTF-8 -pl :xxx-admin-end -am

6.3 将文件导入到postman中

6.4 配置环境变量替换server

smart-doc的使用相关推荐

Smart—doc配置
Smart-doc配置依赖 <dependency><groupId>com.github.shalousun</groupId><artifactId&g ...
我的软件推广成功之路 [转]
我的软件推广成功之路本人与大家一样,原来只是一个普通的程序员,靠给软件公司打工谋生.后来感觉这样长期干下去没有什么前途,虽然现在年轻还可以加班加点靠拼身体吃饭,以后年纪大了怎么办?听说很多人自己单干 ...
smart-doc初体验-springboot生成自动文档
smart-doc初体验一.为什么要引入smart-doc? 二.对比swagger 三.使用四.讨论 1.设计先行模式 2.代码先行五.体验六.附录 1.完整的配置项: 2.官方地址: 一. ...
猿创征文｜小而巧的API文档生成工具之smart-doc
文章目录 smart-doc介绍 smart-doc特性 smart-doc的最佳搭档谁在使用smart-doc smart-doc的优缺点 smart-doc和swagger区别比较 smart- ...
我的软件推广成功之路
本人与大家一样,原来只是一个普通的程序员,靠给软件公司打工谋生.后来感觉这样长期干下去没有什么前途,虽然现在年轻还可以加班加点靠拼身体吃饭,以后年纪大了怎么办?听说很多人自己单干每年靠共享软件都可以赚 ...
PDF与doc格式互换
PDF与doc格式互换在当今的计算机世界里,使用率最高的两种文档方式分别是Microsoft Word的Doc格式和Adobe Acrobat的Pdf格式文件.由于微软的***,我们现在所使用的绝大 ...
android流量监控步骤_Android流量网络监控设计(超级实用版).doc
Android流量网络监控设计(超级实用版).doc 摘要伴随着Android智能移动设备的普及,其对网络系统和流量监控的要求越来越高,因而,让用户有能力实现对移动设备网络流量的实时监控和显示,同 ...
linux嵌入式智能家居环境监测系统的设计,智能家居环境监测系统.doc
智能家居环境监测系统.doc 智能家居环境监测系统近些年来,智能家居系统的使用功能愈加健全.本文之中在充分了解嵌入式系统平台的具体构建的前提下,以智能家居系统当前的功能要求为主要方向,以该平台的硬件 ...
odoo学习必看-提问的智慧《How To Ask Questions The Smart Way》
odoo学习必看-提问的智慧<How To Ask Questions The Smart Way> 人必自助而后人助之,而后天助之.出自<周易·系辞上> 访问原文感觉这篇文 ...
产品需求分析与市场分析方法汇总（SWOT+PDCA+波士顿矩阵BCG+5W2H分析法+STAR关键事件分析法+目标管理SMART+时间管理紧急重要矩阵+WBS任务分解法）
产品需求分析与市场分析方法汇总(SWOT+PDCA+波士顿矩阵BCG+5W2H分析法+STAR关键事件分析法+目标管理SMART+时间管理紧急重要矩阵+WBS任务分解法) 产品需求分析与市场分析方法汇 ...

smart-doc的使用