smart-doc从2018年8月份底开源发布以来已经迭代了好几个版本。在这里非常感谢那些敢于用smart-doc去做尝试并积极提出建议的社区用户。因此决定在本博客中重要说明下smart-doc的功能，包括使用介绍。以减少后期用户使用中的一些疑惑。
一、简介
Smart-doc是一个完全无侵入的java Rest Api文档生成工具。让用户的代码保持整洁一直是Smart-doc的核心理念。smart-doc官方已经开发出了maven和gradle插件，因此我们不再推荐使用单元测试集成smart-doc。使用插件的文档效果更佳，集成到项目中也很方便。插件是为smart-doc赋能的。 因此本文当前看看就好，直接管官方仓库中的wiki文档介绍更全。
二、特殊功能介绍
2.1 JSR303支持
在当前许多的web项目中，我们都会直接使用JSR303来验证参数的合法性包括检验参数是否为必须参数等，smart-doc本身是为了帮助开发人员少去写一些无用的东西，整合标准的开发规范去帮助快速的生成文档。因此smart-doc自诞生那一刻起就已经支持JRS303验证规范。只要你写在字段上加了JSR303的验证注解或者是hibernate-validate的注解。smart-doc在输出请求参数文档时自动填写参数必填为true。请看代码片段：
public class Leader {
/**
* 姓名
*/
@NotEmpty
@Length(max = 5)
private String name;
/**
* 生日
*/
@NotBlank(message = "生日不能为空")
@Pattern(regexp = "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", message = "出生日期格式不正确")
private String birthday;
/**
* 年龄
*/
@Min(value = 0)
private Integer age;
/**
* 科目
*/
@Valid
@NotNull(message = "")
private Subject subject;
}
参数请求文档：
| name | string | 姓名 | true |
| birthday | string | 生日 | true |
| age | int | 年龄 | false |
| subject | object | 科目 | true |
| └─subjectName | string | 科目名称 | true |
2.2 响应字段忽略
smart-doc能够自动解析fastjson和jackson的忽略字段注解正确输出到文档中。这个比较简单就不详细介绍了。
2.3 json数据响应字段别名识别
smart-doc能够解析fastjson的JSONField注解的name属性值和spring boot原始的jackson的JsonProperty注解value属性值来自动完成别名输出。做过json字段忽略都知道，这里简单介绍。
public class SubUser {
/**
* 用户名称
*/
private String subUserName;
/**
*
*/
private BigInteger numbers;
/**
* 身份证
*/
@JSONField(name = "id_card")
private String idCard;
}
Response-fields:
| subUserName | string | 用户名称 |
| numbers | number | No comments found. |
| id_card | string | 身份证 |
Response-example:
{
"subUserName":"黎昕.郑",
"numbers":gzc1l6,
"id_card":"370809198201092228"
}
2.4 请求参数忽略
开发中有时候我们可能有时候会直接使用数据库的对象模型去直接接收参数，但是像createTime、updateTime这样的字段我们是不希望输出到请求参数接口文档中。对于返回数据来说，其实比较好处理，smart-doc本身能够识别fastjson和jackson的字段忽略注解来过滤掉。对请求参数来说针对这种都没有好的解决，很多文档工具是通过添加注解，smart-doc经过使用频率和遵循不引入注解的原则，添加一个注释tag来提供请求参数过滤，这个注释tag定义为ignore。 注意：该功能在1.5版本才会有。
public class SubUser {
/**
* 用户名称
*/
private String subUserName;
/**
* 身份证
*/
private String idCard;
/**
* 性别
* @required
*/
private int gender;
/**
* 创建时间
* @ignore
*/
private Timestamp createTime;
}
在Controller层用SubUser作为参数接收，smart-doc输出的参数请求文档：
| subUserName | string | 用户名称 | false |
| numbers | number | No comments found. | false |
| idCard | string | 身份证 | false |
| gender | int | 性别 | true |
2.5 参数自动模拟值生成
smart-doc为了尽量减少开发人员和测试人员造参数值的时间，针对常见的字段类型和常用字段命名规则提供自动造参数值的功能。下面直接看用例:
public class SubUser {
/**
* 姓名
*/
private String name;
/**
* 年龄
*/
private int age;
/**
* 身份证
*/
@JSONField(name = "id_card")
private String idCard;
/**
* 性别(0,1)
*
*/
private int gender;
/**
* 电子邮件
*/
private String email;
/**
* 手机号
*/
private String phone;
/**
* 创建时间
* @ignore
*/
private Timestamp createTime;
}
下面是smart-doc自定生成文档中响应数据，这个数据全部依赖源码来推导完成。
Response-fields:
| name | string | 姓名 |
| age | int | 年龄 |
| id_card | string | 身份证 |
| gender | int | 性别(0,1) |
| string | 电子邮件 | |
| phone | string | 手机号 |
| createTime | object | 创建时间 |
Response-example:
{
"name":"明轩.石",
"age":59,
"id_card":"350308197203301780",
"gender":0,
"email":"聪健.邱@gmail.com",
"phone":"17664304058",
"createTime":"2018-10-23 00:20:19"
}
2.6 添加文档变更记录
在1.7版本开始，smart-doc添加了文档变更记录的记录功能，生成的文档更加符合实际的文档交互场景。该功能需要在选择使用allInOne设置的时候才生效。 使用方式如下：
ApiConfig config = new ApiConfig();
config.setServerUrl("http://localhost:8080");
config.setAllInOne(true);
config.setOutPath("d:\\md2");
//不指定SourcePaths默认加载代码为项目src/main/java下的
config.setSourceCodePaths(
SourceCodePath.path().setDesc("本项目代码").setPath("src/main/java")
);
//非必须项，只有当setAllInOne设置为true时文档变更记录才生效，
//https://gitee.com/sunyurepository/ApplicationPower/issues/IPS4O
config.setRevisionLogs(
RevisionLog.getLog().setRevisionTime("2018/12/15").setAuthor("chen").setRemarks("测试").setStatus("创建").setVersion("V1.0"),
RevisionLog.getLog().setRevisionTime("2018/12/16").setAuthor("chen2").setRemarks("测试2").setStatus("修改").setVersion("V2.0")
);
变更记录在文档头部，markdown样式如下
| V1.0 | 2018/12/15 | 创建 | chen | 测试 |
| V2.0 | 2018/12/16 | 修改 | chen2 | 测试2 |
2.7 记录字段变更版本
smart-doc的用户在使用中提出了新增记录字段变更版本的需求。这样能够方便知道某一接口的接收参数字段或者是响应字段是什么时候新增的。秉承着简洁的原则，smart-doc在实现这一功能是并未引入额外的注释tag，而是直接利用了JAVA原生的@since这个tag来标记字段新增的版本。用例如下：
public class SubUser {
/**
* @since 1.0
* 用户名称
*/
private String subUserName;
/**
* 身份证
*/
private String idCard;
/**
* 性别
* @required
*/
private int gender;
/**
* 创建时间
* @ignore
*/
private Timestamp createTime;
}
Response-fields:
| subUserName | string | 用户名称 | false | 1.0 |
| numbers | number | No comments found. | false | - |
| idCard | string | 身份证 | false | - |
| gender | int | 性别 | true | - |
三、如何让smart-doc加载源码
Smart-doc作为一款完全依赖源码注释来分析生成文档的工具。如果没有源代码，那么在生成文档时将只能看到字段名和字段类型等信息，注释相关的信息都将无法生成，对于一个所有代码都在一个单独项目中的情况，你不需要考虑人和东西，Smart-doc能完美的完成你想要的文档，但是对一个多模块项目，或者项目依赖了一个独立的jar包的情况，smart-doc将无法加载到它所运行模块之外的代码。下面将会介绍如何来让Smart-doc加载到运行模块外的项目代码：
3.1 通过ApiConfig类设置
代码示例如下：
ApiConfig config = new ApiConfig();
//以前的版本为setSourcePaths，SourceCodePath为SourcePath
config.setSourceCodePaths(
SourceCodePath.path().setDesc("本项目代码").setPath("src/main/java"),
//smart-doc对路径自动会做处理，无论是window合适linux系统路径，直接拷贝贴入即可
SourceCodePath.path().setDesc("加载外部项目源码").setPath("E:\\Test\\Mybatis-PageHelper-master\\src\\main\\java")
);
这样smart-doc就能将外部的源码载入。
注意：smart-doc后续版本开发配套的插件可以实现自动加载source源码，推荐使用插件。
3.2 通过maven的classifier来指定源码包
这里先看如何使用classifier来加载源码包。
<!--依赖的库-->
<dependency>
<groupId>com.github.shalousun</groupId>
<artifactId>common-util</artifactId>
<version>[最新版本]</version>
</dependency>
<!--依赖库源码-->
<dependency>
<groupId>com.github.shalousun</groupId>
<artifactId>common-util</artifactId>
<version>[最新版本]</version>
<classifier>sources</classifier>
<!--设置为test,项目发布时source不会放入最终的产品包-->
<scope>test</scope>
</dependency>
这样不需要像上面一样设置源码加载路径了。但是并不是所有的打包都能有源码包。需要在打包是做规范化处理。
注意：smart-doc后续版本开发配套的插件可以实现自动加载source源码，推荐使用插件。
公有jar包打规范
当你发布公共jar包或者dubbo应用api接口共有jar包时，在maven的plugs中加入maven-source-plugin,示例如下：
<!-- Source -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>3.1.0</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>jar-no-fork</goal>
</goals>
</execution>
</executions>
</plugin>
这样发布的时候就会生成一个[your jar name]-sources.jar的源码包，这个包也会一起发布到私有仓库。这样就可以通过classifier来指定sources了。如果还是不清楚可以直接参考smart-doc源码的pom.xml配置。使用单元测试模式需要在依赖中配置，目前smart-doc的插件已经能够自动加载发布到仓库中sources.jar，推荐使用插件。
注意： 经测试如果只是通过install到本地，即便是指定了sources也无法读取到源码，只有将公用的模块deploy到nexus这样的私服上才能正常使用。
四、在Spring Boot项目中生成和展示html文档
smart-doc支持直接生成html静态文档，推荐生成的文档放到项目src/main/resources/static/doc的目录下，部署好服务后直接访问http://localhost:8080/doc/api.html即可看到一个类似gitbook带完美书签的html文档，文档风格简洁明了。操作步骤如下：
4.1 生成html文档
编写生成文档的单元测试；代码如下：
/**
* 包括设置请求头，缺失注释的字段批量在文档生成期使用定义好的注释
*/
@Test
public void testBuilderControllersApi() {
ApiConfig config = new ApiConfig();
config.setServerUrl("http://localhost:8080");
//设置用md5加密html文件名,不设置为true，html的文件名将直接为controller的名称
config.setMd5EncryptedHtmlName(true);
config.setStrict(true);//true会严格要求注释，推荐设置true
config.setOutPath(DocGlobalConstants.HTML_DOC_OUT_PATH);//输出到static/doc下
//不指定SourcePaths默认加载代码为项目src/main/java下的,如果项目的某一些实体来自外部代码可以一起加载
config.setSourceCodePaths(
SourceCodePath.path().setDesc("本项目代码").setPath("src/main/java")
);
long start = System.currentTimeMillis();
HtmlApiDocBuilder.builderControllersApi(config);//此处使用HtmlApiDocBuilder，ApiDocBuilder提供markdown能力
long end = System.currentTimeMillis();
DateTimeUtil.printRunTime(end, start);
}
4.2 修改服务配置
如果Spring Boot服务配置了spring.resources.add-mappings=false，那么服务器将不会处理静态资源， smart-doc生成的html静态api文档也就不能访问，此时只需要将配置改为true即可。当然这种配置最好放入配置中心， 真正的生产服务器如果不希望暴露接口文档可以直接设置为false关闭文档。
4.3 html静态api展示效果
五、smart-doc自定义注释tag
| @ignore | ignore tag用于过滤请求参数对象上的某个字段，设置后smart-doc不输出改字段到请求参数列表中。 |
| @required | 如果你没有使用JSR303参数验证规范实现的方式来标准字段，就可以使用@required去标注请求参数对象的字段，标注smart-doc在输出参数列表时会设置为true。 |
最佳实践
首先smart-doc的实现思路是从源码出手，源码分析上存在着许多的难点，因此对接口代码的规范度要求很高。在smart-doc开源以来的反馈看，代码规范度高，碰到的问题也比较少。下面几点使用建议：
- 建议公司内部代码尽量规范统一。