文档章节

smart-doc功能使用介绍

上官胡闹
 上官胡闹
发布于 2018/10/22 23:33
字数 1373
阅读 351
收藏 4

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

参数请求文档:

ParameterTypeDescriptionRequired
namestring姓名true
birthdaystring生日true
ageint年龄false
subjectobject科目true
└─subjectNamestring科目名称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:

FieldTypeDescription
subUserNamestring用户名称
numbersnumberNo comments found.
id_cardstring身份证

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输出的参数请求文档:

ParameterTypeDescriptionRequired
subUserNamestring用户名称false
numbersnumberNo comments found.false
idCardstring身份证false
genderint性别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:

FieldTypeDescription
namestring姓名
ageint年龄
id_cardstring身份证
genderint性别(0,1)
emailstring电子邮件
phonestring手机号
createTimeobject创建时间

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.02018/12/15创建chen测试
V2.02018/12/16修改chen2测试2

© 著作权归作者所有

共有 人打赏支持
上官胡闹
粉丝 54
博文 82
码字总数 58816
作品 1
成都
程序员
私信 提问
smart-doc 1.5 发布,Java 零注解文档生成工具

smart-doc是一个java restful api文档生成工具,smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档的实现方法。smart-doc完全基于接口源码分析来生成接口文档,完全做到零注解侵...

上官胡闹
2018/10/23
727
2
smart-doc 1.6 发布,Java 零注解文档生成工具

smart-doc是一个java restful api文档生成工具,smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档的实现方法。smart-doc完全基于接口源码分析来生成接口文档,完全做到零注解侵...

上官胡闹
2018/12/11
0
0
PS-SMART及参数服务(Parameter Server)

前天第二届阿里云安全算法挑战赛终于胜利结束了,得了个季军,虽然名次不是最理想的,不过很高兴能认识一大群数据达人,整个比赛的过程也很让人享受。这次比赛过程中我在对网页内容进行分析的...

北方的郎
2018/01/10
0
0
Java 零注解文档生成工具 smart-doc 1.2 发布

smart-doc是一个java restful api文档生成工具,smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档的实现方法。smart-doc完全基于接口源码分析来生成接口文档,完全做到零注解侵...

上官胡闹
2018/09/04
1K
5
关于java web restful api文档的重新探索

一、背景 在当今各种盛行的前后端分离、restful service开发过程中,接口文档是必不可少的。对于前后端分离的开发中,后端开发需要将接口写好后需要告诉前端工程师接口的请求参数、响应示例等...

上官胡闹
2018/08/20
0
8

没有更多内容

加载失败,请刷新页面

加载更多

mysql grant 用户权限总结

用户权限管理主要有以下作用: 1. 可以限制用户访问哪些库、哪些表 2. 可以限制用户对哪些表执行SELECT、CREATE、DELETE、DELETE、ALTER等操作 3. 可以限制用户登录的IP或域名 4. 可以限制用...

Airship
9分钟前
0
0
RabbitMQ学习(3)

1. 消费端 1. 消费端通过推模式或者拉模式从RabbitMQ中获取并消费消息,当消费者确认处理消息后,可以手动确认消息已被接收,然后就会将该消息从RabbitMQ的队列中标记再清除,消费者端还可以...

江左煤郎
20分钟前
0
0
linux mysql(5.7)开启慢查询

一、有3个配置需要设置, 1:相关开关 2:日志目录文件 3:慢查询的时间限制 二、设置完之后重启mysql service mariadb restart 三、重启后做个测试 连接mysql 并查询: select sleep(6); 四...

chro008
27分钟前
0
0
选择IDC机房、选择硬件、上架服务器、装系统

选择IDC机房 当业务量比较大的时候,往往选用IDC而不是公有云来跑业务。 IDC机房的服务一般分为两种 需要我们自己购买服务器和网络设备,托管到IDC机房。IDC机房会提供布线、巡检、硬件操作等...

李超小牛子
29分钟前
1
0
《傲慢与偏见》的读书笔记与读后感作文2400字

《傲慢与偏见》的读书笔记与读后感作文2400字: 作者:孙苑馨;笔者按:读书这个习惯是我爸妈养出来的。小时候父母赚的钱除了吃饭穿衣剩下的就是买书了,他们除了买各种新鲜出版的文艺派图书...

原创小博客
37分钟前
3
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部