smart-doc简介
官方地址smart-doc
smart-doc 是一款同时支持 JAVA REST API 和 Apache Dubbo RPC 接口文档生成的工具，smart-doc 在业内率先提出基于 JAVA 泛型定义推导的理念， 完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。你只需要按照 java-doc 标准编写注释， smart-doc 就能帮你生成一个简易明了的 Markdown、Postman Collection2.0+、OpenAPI 3.0 + 的文档。除此之外 smart-doc 还支持生成漂亮简洁可调试的 html5 页面文档。
资讯来源开源中国
相信很多还在用swagger，但是swagger复杂的配置和入侵式代码增大了开发量。smart-doc相对对基于java标准注解的无入侵的在这方便完胜swagger。
smart-doc使用
smart-doc快速入门
生成md文档
参考自smart-doc生成java 接口文档
导入依赖
严格模式下，会检测javadoc,如过没写注释会抛出异常
接口注释
/**
* 评论控制器
*/
@RestController
@RequestMapping("/comment")
public class CommentController {
/**
* 添加评论
* @return
* @param comment 品论
*/
@GetMapping("/add")
void addComment(Comment comment){
System.out.println("添加评论");
}
/**
* 删除评论
* @param id 编号
* @return
*/
@GetMapping("/delete")
void deleteComment(Integer id){
System.out.println("删除评论");
}
/**
* 删除评论
* @param id 编号
* @return
*/
@GetMapping("/update")
void updateComment(Integer id){
System.out.println("编辑评论");
}
/**
* 查询评论
* @return
*/
@GetMapping("/query")
ResponseData queryComment(){
Comment comment = new Comment();
comment.setName("_小许_");
comment.setAvatar("https://www.xiaoxu.com/picture/xiaoxu.jpg");
comment.setType(1);
comment.setCreateTime(new Date());
List l = new ArrayList();
l.add(comment);
return ResponseData.SuccessRes(l);
}
}
在控制器上至少有一个注释评论控制器，在url上也是至少有一个添加评论另外两个根据实际即可，注意没有参数不要写@param不然会报错。
参数和返回值注释
/**
* 评论表
*
* @author admin
* @date 2023/03/02
*/
@Data
public class Comment {
/** 姓名 */
private String name;
/**
* 头像
*/
private String avatar;
/**
* 评论
*/
private String comment;
/**
* 创建时间
*/
private Date createTime;
/**
* 状态
*/
private Integer type;
}
参数和返回值注释至少有/** 姓名 */注释，不然smart-doc生产文档的字段无注释。
配置启动类生产文档
@Test
public void testBuilderControllersApiSimple() {
ApiConfig config = new ApiConfig();
//服务地址
config.setServerUrl("http://localhost:8010");
//生成到一个文档
config.setAllInOne(true);
//采用严格模式
config.isStrict();
//文档输出路径
config.setOutPath("src/main/resources/static/doc");
ApiDocBuilder.builderControllersApi(config);
//将生成的文档输出到src/main/resources/static/doc目录下，严格模式下api-doc会检测Controller的接口注释
}
服务器地址是生产文档的示例地址，在导入postman，apifox等工具时有用，本地参考随意设计即可；设置严格模式smart-doc会严格检查注释，文档输出路径可以是相对路径也可以是绝对路径，但一般用相对路径./(默认为根项目路径)。上面配置生成类需要再spring环境中执行，直接在单元测试类配置即可。
如下图所示生成了一个AllInOne.md的文件：
生成了md的api文档，全程只引入了一个依赖，配置了一个生成器就完成了api接口的生成而且界面简精简，是不是非常方便。
md已经生成到了templates，通过流的处理也可以在线文档观看，smart-doc也提供了maven和gradle的插件功能，用于生成文档，html和导入到postman工具。
生成html文档
导入依赖
resources目录下新增smart-doc.json配置文件文件
{
"serverUrl": "http://127.0.0.1:8080/api-demo/", //设置服务器地址,非必须
"isStrict": false, //是否开启严格模式
"allInOne": true, //是否将文档合并到一个文件中，一般推荐为true
"coverOld": true, //是否覆盖旧的文件，主要用于mardown文件覆盖
"packageFilters": "",//controller包过滤，多个包用英文逗号隔开
"outPath": "src/main/resources/static/doc", //指定文档的输出路径
"md5EncryptedHtmlName": false,//只有每个controller生成一个html文件是才使用
"projectName": "CMP基础服务API文档",//配置自己的项目名称
"showAuthor":true, //是否显示接口作者名称，默认是true,不想显示可关闭
"dataDictionaries": [ //配置数据字典，没有需求可以不设置
{
"title": "状态字典",
"enumClassName": "cn.xx.docStatusEnum",
"codeField": "key",
"descField": "value"
}
]
}
maven运行,将会扫描controller生成文档,文档地址在上面定义的outPath参数
//生成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
tag名称描述@ignoreignore tag用于过滤请求参数对象上的某个字段，设置后smart-doc不输出改字段到请求参数列表中。关于响应字段忽略的请看忽略响应字段，如果ignore加到方法上，则接口方法不会输出到文档。@required如果你没有使用JSR303参数验证规范实现的方式来标注字段，就可以使用@required去标注请求参数对象的字段，标注smart-doc在输出参数列表时会设置为true。@mock从smart-doc 1.8.0开始，mock tag用于在对象基本类型字段设置自定义文档展示值。设置值后smart-doc不再帮你生成随机值。方便可以通过smart-doc直接输出交付文档
springboot项目使用smart-doc生成api html文档
smart-doc官方文档
smart标签用法
生成了html和css，打开后如下所示：
在文档中，Required 和Since都是默认值，通过smart-doc的标签来更改：
@ignore忽略标签用于筛选请求参数对象上的某个字段。@required设置某字段为必填或非必填
smart-doc 使用说明
由于生成的是html文件所以可以随服务一同部署，如下生成html文件
配置文件释放静态资源
spring.mvc.static-path-pattern=/static/**
spring视图解析器都是从resource下开始找相关文件的，因此插件生成的css是无法自动找到的，所以需要重新配置：
编写资源控制器：
@Controller
public class DocController {
@GetMapping("/doc")
public String getDoc(){
return "static/doc/index.html";
}
}
由于smart-doc是对源码的解析，所以每次改动源码都需要重新编译。
好文链接
发表评论