smart-doc是一个java restful api文档生成工具，smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档的实现方法。smart-doc完全基于接口源码分析来生成接口文档，完全做到零注解侵入，你只需要按照java标准注释的写，smart-doc就能帮你生成一个简易明了的markdown或是一个像GitBook样式的静态html文档。
下面将介绍如何在Spring Boot项目中集成smart-doc生成一个简明的api文档。
注意： smart-doc已经被开源中国收录，并且开始被国内很多开发者使用到自己项目中快速生成接口文档。
smart-doc功能
- 零注解、零学习成本、只需要写标准java注释。
- 基于源代码接口定义自动推导，强大的返回结构推导。
- 支持Spring MVC,Spring Boot,Spring Boot Web Flux(controller书写方式)。
- 支持Callable,Future,CompletableFuture等异步接口返回的推导。
- 支持JavaBean上的JSR303参数校验规范。
- 对json请求参数的接口能够自动生成模拟json参数。
- 对一些常用字段定义能够生成有效的模拟值。
- 支持生成json返回值示例。
- 支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。
- 支持生成多种格式文档：Markdown、HTML5、Asciidoctor。
- 轻易实现在Spring Boot服务上在线查看静态HTML5 api文档。
- 开放文档数据，可自由实现接入文档管理系统。
在Spring Boot项目中集成Smart-doc
添加smart-doc依赖，注意打包后不需要将smart-doc打入最终的产品包，因此我推荐只用test级别就可以了。
<dependency>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc</artifactId>
<version>1.7.0</version>
<scope>test</scope>
</dependency>新建一个对象：
public class User {
/**
* 用户名
*/
private String userName;
/**
* 昵称
*/
private String nickName;
/**
* 用户地址
*/
private String userAddress;
/**
* 用户年龄
*/
private int userAge;
/**
* 手机号
*/
private String phone;
/**
* 创建时间
*/
private Long createTime;
/**
* ipv6
*/
private String ipv6;
/**
* 固定电话
*/
private String telephone;
//省略get set
}下面来新建一个UserController，然后将User作为Controller的请求参数和响应实体测试下smart-doc是如何轻松完成文档生成的。
@RestController
@RequestMapping("/user")
public class UserController {
/**
* 添加用户
* @param user
* @return
*/
@PostMapping("/add")
public User addUser(@RequestBody User user){
return null;
}
}添加完成controller后，我们在项目中新建一个单元测试类用于跑文档。
public class ApiDocTest {
/**
* 包括设置请求头，缺失注释的字段批量在文档生成期使用定义好的注释
*/
@Test
public void testBuilderControllersApi() {
ApiConfig config = new ApiConfig();
config.setServerUrl("http://localhost:8080");
//true会严格要求注释，推荐设置true
config.setStrict(true);
//true会将文档合并导出到一个markdown
//config.setAllInOne(true);
//生成html时加密文档名不暴露controller的名称
config.setMd5EncryptedHtmlName(true);
//指定文档输出路径
//@since 1.7 版本开始，选择生成静态html doc文档可使用该路径：DocGlobalConstants.HTML_DOC_OUT_PATH;
config.setOutPath("d:\\md");
// @since 1.2,如果不配置该选项，则默认匹配全部的controller,
// 如果需要配置有多个controller可以使用逗号隔开
config.setPackageFilters("com.power.doc.controller");
long start = System.currentTimeMillis();
//获取接口数据后自行处理
ApiDocBuilder.builderControllersApi(config);
long end = System.currentTimeMillis();
DateTimeUtil.printRunTime(end, start);
}
}最后运行一下单元测试smart-doc即可生成markdown接口文档到指定的目录。
文档生成效果
用户信息操作接口
添加用户
URL: http://localhost:8080/user/add
Type: POST
Content-Type: application/json; charset=utf-8
Request-parameters:
| Parameter | Type | Description | Required | Since |
|---|---|---|---|---|
| userName | string | 用户名 | false | - |
| nickName | string | 昵称 | false | - |
| userAddress | string | 用户地址 | false | - |
| userAge | int | 用户年龄 | false | - |
| phone | string | 手机号 | false | - |
| createTime | number | 创建时间 | false | - |
| ipv6 | string | ipv6 | false | - |
| telephone | string | 固定电话 | false | - |
Request-example:
{
"userName":"鹏飞.贺",
"nickName":"raymond.gutkowski",
"userAddress":"Apt. 819 萧旁7699号， 章丘， 滇 852063",
"userAge":41,
"phone":"15018373016",
"createTime":1569934393095,
"ipv6":"9eb3:fada:ffd2:912e:6225:1062:a2d7:718f",
"telephone":"15018373016"
}Response-fields:
| Field | Type | Description | Since |
|---|---|---|---|
| userName | string | 用户名 | - |
| nickName | string | 昵称 | - |
| userAddress | string | 用户地址 | - |
| userAge | int | 用户年龄 | - |
| phone | string | 手机号 | - |
| createTime | number | 创建时间 | - |
| ipv6 | string | ipv6 | - |
| telephone | string | 固定电话 | - |
Response-example:
{
"userName":"鹏飞.贺",
"nickName":"raymond.gutkowski",
"userAddress":"Apt. 819 萧旁7699号， 章丘， 滇 852063",
"userAge":41,
"phone":"15018373016",
"createTime":1569934393095,
"ipv6":"9eb3:fada:ffd2:912e:6225:1062:a2d7:718f",
"telephone":"15018373016"
}是不是比swagger简单很多呢，而且还完全不侵入代码，只需要写上标准的java doc注释。需要了解更多多情况请查看smart-doc项目，好用请记得点star哦。查看smart-doc项目
注意: 本文来自smart-doc原作者，您可以转载但请勿copy充当原创。