Knife4j添加lombok及注解初探

一、POM添加

在pom文件里添加包

       <!-- 添加Lombok插件-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>

二、使用及注解介绍

• 创建实体类
  

  package com.mrliu.undertow.pojo;
  
  import io.swagger.annotations.ApiModel;
  import io.swagger.annotations.ApiModelProperty;
  import lombok.Data;
  
  /**
   * 商品实体类
   *
   * @author liuyangos8888
   */
  
  @Data
  public class Commodity {
  
  
      /**
       * int 类型主键设置方式
       */
      private int id;
  
  }

• 添加注解
  

  package com.mrliu.undertow.pojo;
  
  import io.swagger.annotations.ApiModel;
  import io.swagger.annotations.ApiModelProperty;
  import lombok.Data;
  
  /**
   * 商品实体类
   *
   * @author liuyangos8888
   */
  
  @Data
  @ApiModel(value = "商品类", description = "用于存储商品对象的字段",
          discriminator = "SpecialCommodity", subTypes = SpecialCommodity.class, reference = "子类是其相关类")
  public class Commodity {
  
  
      /**
       * int 类型主键设置方式
       */
      @ApiModelProperty(name = "类型主键", dataType = "int",
              required = true, value = "自动生成", notes = "自动生成的ID,查询中使用")
      private int id;
  
  
      @ApiModelProperty(name = "特殊商品类", dataType = "SpecialCommodity",
              required = true, notes = "特殊商品实体类")
      private SpecialCommodity specialCommodity;
  }

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

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

         使用实例:

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

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

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

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

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

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

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

@ApiModel(value = "商品类")

   @ApiModelProperty : 字段描述注解

   参数

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

   使用实例:

         注解加载在字段上

   常用模型:

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