2019独角兽企业重金招聘Python工程师标准>>>

smart-doc从8月份底开始开源发布到目前为止已经迭代了几个版本。在这里非常感谢那些敢于用smart-doc去做尝试并积极提出建议的社区用户。因此决定在本博客中重要说明下smart-doc的功能，包括使用介绍。以减少后期用户使用中的一些疑惑。

一、简介

关于 smart-doc在我的《关于java web restful api文档的重新探索》博客已经介绍过，这里不再赘述，一些常用的也有介绍。下面将直接介绍smart-doc提供的一些特殊功能。

二、特殊功能介绍

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;
}

参数请求文档：

Parameter	Type	Description	Required
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:

Field	Type	Description
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输出的参数请求文档：

Parameter	Type	Description	Required
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:

Field	Type	Description
name	string	姓名
age	int	年龄
id_card	string	身份证
gender	int	性别(0,1)
email	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.setSourcePaths(
    SourcePath.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

smart-doc功能使用介绍