目录

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

前言

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

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

<dependency><groupId>io.swagger.core.v3</groupId><artifactId>swagger-annotations</artifactId><version>2.2.19</version></dependency>

主要作用：开发者对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)@Inheritedpublic @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 */@Deprecatedboolean 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;}