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使用
- 生成md文档
导入依赖
<dependency>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc</artifactId>
<version>1.1</version>
<scope>test</scope>
</dependency>
严格模式下,会检测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文档
导入依赖
<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>1.0.3</version>
<configuration>
<!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
<configFile>./src/main/resources/smart-doc.json</configFile>
<!--指定项目名称-->
<projectName>API文档</projectName>
</configuration>
<executions>
<execution>
<!--如果不需要在执行编译时启动smart-doc,则将phase注释掉-->
<phase>compile</phase>
<goals>
<goal>html</goal>
</goals>
</execution>
</executions>
</plugin>
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名称 | 描述 |
---|---|
@ignore | ignore 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文档
生成了html和css,打开后如下所示:
在文档中,Required
和Since
都是默认值,通过smart-doc的标签来更改:
@ignore
忽略标签用于筛选请求参数对象上的某个字段。@required
设置某字段为必填或非必填
由于生成的是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是对源码的解析,所以每次改动源码都需要重新编译。