smart-doc是什么？
smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具，零注解、零学习成本、只需要写标准JAVA注释，smart-doc就能帮你生成一个简易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+的文档。
smart-doc怎么用？
1、Add Maven Plugin
<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>2.2.4.1</version>
<configuration>
<!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
<configFile>./src/main/resources/smart-doc.json</configFile>
<!--指定项目名称-->
<projectName>测试</projectName>
<!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉-->
<excludes>
<!--格式为：groupId:artifactId;参考如下-->
<exclude>com.alibaba:fastjson</exclude>
</excludes>
<!--自1.0.8版本开始，插件提供includes支持,配置了includes后插件会按照用户配置加载而不是自动加载，因此使用时需要注意-->
<!--smart-doc能自动分析依赖树加载所有依赖源码，原则上会影响文档构建效率，因此你可以使用includes来让插件加载你配置的组件-->
<includes>
<!--格式为：groupId:artifactId;参考如下-->
<!--也可以支持正则式如：com.alibaba:.* -->
<include>com.alibaba:fastjson</include>
</includes>
</configuration>
<executions>
<execution>
<goals>
<!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
<goal>html</goal>
</goals>
</execution>
</executions>
</plugin>
2、在项目目录下添加 smart-doc.json 配置文件，常用配置如下
{
"serverUrl": "http://localhost:8080", //服务器地址,非必须。导出postman建议设置成http://{{server}}方便直接在postman直接设置环境变量
"allInOne": true, //是否将文档合并到一个文件中，一般推荐为true
"outPath": "src/main/resources/static/doc", //指定文档的输出路径
"coverOld": true, //是否覆盖旧的文件，主要用于mardown文件覆盖
"createDebugPage": true,//@since 2.0.0 smart-doc支持创建可以测试的html页面，仅在AllInOne模式中起作用。
"projectName": "smart-doc",//配置自己的项目名称
"sortByTitle":false,//接口标题排序，默认为false,@since 1.8.7版本开始
"showAuthor":true,//是否显示接口作者名称，默认是true,不想显示可关闭
"allInOneDocFileName":"index.html"//自定义设置输出文档名称, @since 1.9.0
}
3、在对应的接口、实体类中添加上标准JAVA注释
/**
* 根据用户id获取用户
* @param id
* @return
*/
@GetMapping("user/{id}")
public R<User> getUser(@PathVariable Integer id){
User user = new User();
user.setId(id);
user.setUsername("王大福");
return R.ok(user);
}
4、利用maven插件，生成接口文档
1.1 在idea中，可以直接通过maven helper中Plugins，smart-doc插件中生成对应的文档
1.2 maven命令方式
//生成html
mvn -Dfile.encoding=UTF-8 smart-doc:html
//生成adoc
mvn -Dfile.encoding=UTF-8 smart-doc:adoc
smart-doc效果示例
html全局展示
请求参数示例
请求响应示例
