smart-doc的使用
目录
1. 什么是smart-doc
2. smart-doc的功能特性
3. smart-doc自定义注释tag
4. 通过引入依赖生成文档
5. 通过集成smart-doc的maven插件生成文档
6. 生成Postman json文件与导入Postman测试
1. 什么是smart-doc
smart-doc是一款同时支持JAVA REST API和[Apache](https://so.csdn.net/so/search?q=Apache&spm=1001.2101.3001.7020) 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标记下载方法)测试。
- 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方法生成
@Testpublic 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 查看文档
-
通过集成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>--> <!--<!–格式为：groupId:artifactId;参考如下–>--> <!--</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命令生成文档
//生成htmlmvn -Dfile.encoding=UTF-8 smart-doc:html//生成markdownmvn -Dfile.encoding=UTF-8 smart-doc:markdown//生成adocmvn -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.5mvn -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
