Knife4j添加lombok及注解初探

SAMXIE 2020-06-14

一、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 : 对象描述注解

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

         使用实例:

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

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 : 字段描述注解

   参数

属性名称数据类型默认值说明
valueString" "字段说明
nameString" "重写属性名字
dataTypeString" "重写属性类型
requiredString" "是否必填 
exampleString" "举例说明
hiddenString" "隐藏

   使用实例:

         注解加载在字段上

   常用模型:

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

相关推荐

末点 / 0评论 2020-06-27