Knife4j添加lombok及注解初探

一、POM添加

在pom文件里添加包

1        <!-- 添加Lombok插件-->
2         <dependency>
3             <groupId>org.projectlombok</groupId>
4             <artifactId>lombok</artifactId>
5             <optional>true</optional>
6         </dependency>

View Code

二、使用及注解介绍

创建实体类

 1 package com.mrliu.undertow.pojo;
 2 
 3 import io.swagger.annotations.ApiModel;
 4 import io.swagger.annotations.ApiModelProperty;
 5 import lombok.Data;
 6 
 7 /**
 8  * 商品实体类
 9  *
10  * @author liuyangos8888
11  */
12 
13 @Data
14 public class Commodity {
15 
16 
17     /**
18      * int 类型主键设置方式
19      */
20     private int id;
21 
22 }

View Code

添加注解

 1 package com.mrliu.undertow.pojo;
 2 
 3 import io.swagger.annotations.ApiModel;
 4 import io.swagger.annotations.ApiModelProperty;
 5 import lombok.Data;
 6 
 7 /**
 8  * 商品实体类
 9  *
10  * @author liuyangos8888
11  */
12 
13 @Data
14 @ApiModel(value = "商品类", description = "用于存储商品对象的字段",
15         discriminator = "SpecialCommodity", subTypes = SpecialCommodity.class, reference = "子类是其相关类")
16 public class Commodity {
17 
18 
19     /**
20      * int 类型主键设置方式
21      */
22     @ApiModelProperty(name = "类型主键", dataType = "int",
23             required = true, value = "自动生成", notes = "自动生成的ID,查询中使用")
24     private int id;
25 
26 
27     @ApiModelProperty(name = "特殊商品类", dataType = "SpecialCommodity",
28             required = true, notes = "特殊商品实体类")
29     private SpecialCommodity specialCommodity;
30 }

View Code

注解详解
实体对象常用添加@ApiModel,即可添加在请求参数上,也可添加在返回结果参数上,添上相应的参数后,就会在文档中显示出来
@ApiModel : 对象描述注解

参数

属性名称	数据类型	默认值	说明
value	String	类名	为模型提供备用名称
description	String	" "	提供详细的类描述
parent	Class<?> parent	Void.class	为模型提供父类以允许描述继承关系
discriminatory	String	" "	支持模型继承和多态，使用鉴别器的字段的名称，可以断言需要使用哪个子类型
subTypes	Class<?>[]	{}	从此模型继承的子类型数组
reference	String	" "	指定对应类型定义的引用，覆盖指定的任何其他元数据

使用实例:

注解加载类头上,然后再括号内添加参数及参数描述的值

1 @ApiModel(value = "商品类", description = "用于存储商品对象的字段")

View Code

一般最常用的参数就是value和description两个参数,会显示在实体对象文档的对应位置,适合前段查阅,其他参数添加了,并未在界面显示出来

其中,value在knife4J和swagger-ui.中均有显示,description在swagger-ui.中有显示,在knife4J并未显示

discriminatory和reference两个String类型的参数,向其中任意添加内容未发现在界面描述中显示内容

subTypes要添加一个类.class,用于指向当前类的子类是谁,后端自己看的,前段看不到 parent 要添加一个类.class,用于指向当前类的父类是谁,后端自己看的,前段看不到

综上所述,在knife4J中,如果仅仅是需要返回api文档,@ApiModel仅需设置一个参数value即可.

1 @ApiModel(value = "商品类")

View Code

@ApiModelProperty : 字段描述注解

参数

属性名称	数据类型	默认值	说明
value	String	" "	字段说明
name	String	" "	重写属性名字
dataType	String	" "	重写属性类型
required	String	" "	是否必填
example	String	" "	举例说明
hidden	String	" "	隐藏

使用实例:

注解加载在字段上

常用模型:

1 @ApiModelProperty(required = true,notes = "时间戳",example = "1567425139000") 
2 private long time;

View Code