Knife4j添加lombok及注解初探

一、POM添加

在pom文件里添加包

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

二、使用及注解介绍

• 创建实体类
  

   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 }

• 添加注解
  

   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 }

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

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

使用实例:

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

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

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

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

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

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

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

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

@ApiModelProperty : 字段描述注解

参数

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

使用实例:

注解加载在字段上

常用模型:

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