【Swagger】JAVA中的@ApiModel和@ApiModelProperty注解[转]

目录

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

前言

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

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

<!-- https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-annotations -->
<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)
@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;

}