smart-doc的使用

参考链接：HOME - Wiki - Gitee.com

目录

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 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