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;