详解JAVA中的@ApiModel和@ApiModelProperty注解

慈云数据 2024-03-22 技术支持 67 0

目录

  • 前言
  • 1. @ApiModel注解
  • 2. @ApiModelProperty注解
  • 3. 实战

    前言

    在Java中,@ApiModel和@ApiModelProperty是Swagger框架(用于API文档的工具)提供的注解,用于增强API文档的生成和展示。这两者搭配使用更佳

    详解JAVA中的@ApiModel和@ApiModelProperty注解
    (图片来源网络,侵删)

    使用两者注解,需导入swagger的依赖包:

    
        io.swagger.core.v3
        swagger-annotations
        2.2.19
    
    

    主要作用:开发者对API的模型和属性进行详细的描述,以便生成清晰的API文档。

    详解JAVA中的@ApiModel和@ApiModelProperty注解
    (图片来源网络,侵删)

    1. @ApiModel注解

    • @ApiModel注解用于对Java类进行标注,表示这个类是一个Swagger模型(Model)。通常用于描述一个数据对象或DTO(Data Transfer Object)。

      示例代码:

      import io.swagger.annotations.ApiModel;
      @ApiModel(description = "用户信息")
      public class User {
          // 类的属性...
      }
      

      深入其源码:

      package io.swagger.annotations;
      import java.lang.annotation.ElementType;
      import java.lang.annotation.Inherited;
      import java.lang.annotation.Retention;
      import java.lang.annotation.RetentionPolicy;
      import java.lang.annotation.Target;
      @Target({ElementType.TYPE})
      @Retention(RetentionPolicy.RUNTIME)
      @Inherited
      public @interface ApiModel {
          String value() default "";
          String description() default "";
          Class parent() default Void.class;
          String discriminator() default "";
          Class[] subTypes() default {};
          String reference() default "";
      }
      

      源码中的注解可看出:

      • @Target注解

        用于指定自定义注解可以应用的程序元素类型,参数是一个ElementType数组。该源码表示应用在类上

      • @Retention注解

        用于指定自定义注解的生命周期,即注解在程序运行时的保留策略。该源码表示运行时

      • @Inherited注解

        子类会继承该注解。默认情况下,注解不会被子类继承。

        对应的属性值为:

        • value属性:属性值,也就是该实体类的描述值,不写默认为实体类的名称,通常描述不清晰才需要value值
        • description属性:描述值,与value不同,该description为较长描述值
        • parent属性:用于指定被注解类的父类
        • discriminator属性:多态情境区分多个子类
        • subTypes属性:指定被注解类的子类
        • reference属性:提供对被注解类的引用信息

          2. @ApiModelProperty注解

          • @ApiModelProperty注解用于对Java类的属性进行标注,表示这个属性是一个Swagger模型的属性。它可以用于描述属性的名称、说明、数据类型等信息
            import io.swagger.annotations.ApiModelProperty;
            public class User {
                @ApiModelProperty(value = "用户ID", example = "123")
                private Long id;
                @ApiModelProperty(value = "用户名", example = "john_doe")
                private String username;
                // 其他属性...
            }
            

            深入其源码:

            @Target({ElementType.METHOD, ElementType.FIELD})
            @Retention(RetentionPolicy.RUNTIME)
            public @interface ApiModelProperty {
                String value() default "";
                String name() default "";
                String allowableValues() default "";
                String access() default "";
                String notes() default "";
                String dataType() default "";
                boolean required() default false;
                int position() default 0;
                boolean hidden() default false;
                String example() default "";
                /** @deprecated */
                @Deprecated
                boolean readOnly() default false;
                AccessMode accessMode() default ApiModelProperty.AccessMode.AUTO;
                String reference() default "";
                boolean allowEmptyValue() default false;
                Extension[] extensions() default {@Extension(
                properties = {@ExtensionProperty(
                name = "",
                value = ""
            )}
            )};
                public static enum AccessMode {
                    AUTO,
                    READ_ONLY,
                    READ_WRITE;
                    private AccessMode() {
                    }
                }
            }
            

            其属性如下:

            • value属性:

              注解的默认属性,理解为注释的作用

            • name属性:

              指定属性或方法的名称,重写该属性名字

            • allowableValues属性:

              指定属性或方法的可接受值范围。

            • access属性:

              指定属性或方法的访问规则。

            • notes属性:

              提供对属性或方法的额外说明。

            • dataType属性:

              指定属性或方法的数据类型。

            • required属性:

              指定属性或方法是否为必需。

            • position属性:

              指定属性或方法在文档中的位置。

            • hidden属性:

              指定属性或方法是否应该在文档中隐藏。

            • example属性:

              提供属性或方法的示例值。

            • readOnly属性(已过时):

              指定属性或方法是否为只读。已过时,推荐使用 access 属性。

            • accessMode属性:

              指定访问模式,可以是 AUTO、READ_ONLY 或 READ_WRITE。

            • reference属性:

              提供属性或方法的引用信息。

            • allowEmptyValue属性:

              指定属性或方法是否允许为空值。

            • extensions属性:

              指定属性或方法的扩展信息,支持一组扩展属性。

            • AccessMode枚举:

              属性或方法的访问模式,包括 AUTO、READ_ONLY 和 READ_WRITE。

              下面是一个简单的示例代码:

              import io.swagger.annotations.ApiModelProperty;
              public class Example {
                  @ApiModelProperty(value = "用户ID", example = "123", required = true)
                  private Long userId;
                  @ApiModelProperty(value = "用户名", example = "码农研究僧", readOnly = true)
                  public String getUsername() {
                      return "码农研究僧";
                  }
              }
              

              3. 实战

              比如应用在技术行业的某个模块,对应数据库中的entity实体类如下:

              @Data
              @TableName("equipment_accident_record")
              @ApiModel(value = "AccidentRecord对象", description = "AccidentRecord对象")
              public class AccidentRecord extends BaseEntity {
              	private static final long serialVersionUID = 1L;
              	/**
              	* 设备编号
              	*/
              		@ApiModelProperty(value = "设备编号")
              		private String equipmentNo;
              	/**
              	* 设备名称
              	*/
              		@ApiModelProperty(value = "设备名称")
              		private String equipmentName;
              	/**
              	* 设备机种
              	*/
              		@ApiModelProperty(value = "设备机种")
              		private String model;
              	/**
              	* 事故日期
              	*/
              		@ApiModelProperty(value = "事故日期")
              		private String dateTime;
              	/**
              	* 操作者
              	*/
              		@ApiModelProperty(value = "操作者")
              		private String operator;
              	/**
              	* 事故经过
              	*/
              		@ApiModelProperty(value = "事故经过")
              		private String content;
              	/**
              	* 损坏情况
              	*/
              		@ApiModelProperty(value = "损坏情况")
              		private String situation;
              	/**
              	* 事故原因
              	*/
              		@ApiModelProperty(value = "事故原因")
              		private String reason;
              	/**
              	* 事故类别
              	*/
              		@ApiModelProperty(value = "事故类别")
              		private String type;
              	/**
              	* 损失费用
              	*/
              		@ApiModelProperty(value = "损失费用")
              		private String expense;
              	/**
              	* 处理意见
              	*/
              		@ApiModelProperty(value = "处理意见")
              		private String opinion;
              	/**
              	* 主管技术员
              	*/
              		@ApiModelProperty(value = "主管技术员")
              		private String technician;
              }
              

              其前端vo类别中的类如下:

              @Data
              @ApiModel(value = "AccidentRecordVO对象", description = "AccidentRecordVO对象")
              public class AccidentRecordVO extends AccidentRecord {
              	private static final long serialVersionUID = 1L;
              }
              
微信扫一扫加客服

微信扫一扫加客服

点击启动AI问答
Draggable Icon