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

目录

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

  前言

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

  
  （图片来源网络，侵删）

  使用两者注解，需导入swagger的依赖包：

  
      io.swagger.core.v3
      swagger-annotations
      2.2.19
  
  

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

  
  （图片来源网络，侵删）

  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;
            }