文档章节

smart-doc功能使用介绍

上官胡闹
 上官胡闹
发布于 10/22 23:33
字数 1154
阅读 159
收藏 0

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

© 著作权归作者所有

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

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

上官胡闹
10/23
0
0
PS-SMART及参数服务(Parameter Server)

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

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

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

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

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

上官胡闹
08/20
0
8
smart-doc 1.0 发布,Java 零注解文档生成工具

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

上官胡闹
08/26
0
0

没有更多内容

加载失败,请刷新页面

加载更多

AS连接网易Mumu模拟器

1、安装模拟器 打开这个网址现在模拟器然后安装 http://mumu.163.com/ 2、安装完成后启动模拟器 3、进入模拟器安装目录 例如本机的安装目录:C:\Program Files (x86)\MuMu\emulator\nemu\vmo...

HGMrWang
12分钟前
5
0
设计要做到扩展性强还挺难的

概述 在日常开发中,有时候你的上司会跟你说,这个模块的设计扩展性要高。把这句话说出来很简单,但是要做到则非常难。导致难的其中一个因素是: 你不熟悉这个行业的业务的玩法 我举个例子来...

Sam哥哥聊技术
14分钟前
2
0
聊聊 scala 的模式匹配

一. scala 模式匹配(pattern matching) pattern matching 可以说是 scala 中十分强大的一个语言特性,当然这不是 scala 独有的,但这不妨碍它成为 scala 的语言的一大利器。 scala 的 patt...

终日而思一
16分钟前
1
0
Spring事物手动回滚

手动回滚: 方法1:在service层方法的catch语句中增加:TransactionAspectSupport.currentTransactionStatus().setRollbackOnly();语句,手动回滚,这样上层就无需去处理异常(现在项目的做法)...

寒风中的独狼
20分钟前
0
0
直角三角形的三角函数

sinA = a/c;A = asin(a/c); 特殊角度的三角函数值

一个小妞
28分钟前
1
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部