前言
在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实体类如下:文章来源:https://www.toymoban.com/news/detail-809500.html
@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类别中的类如下:文章来源地址https://www.toymoban.com/news/detail-809500.html
@Data
@ApiModel(value = "AccidentRecordVO对象", description = "AccidentRecordVO对象")
public class AccidentRecordVO extends AccidentRecord {
private static final long serialVersionUID = 1L;
}
到了这里,关于详解JAVA中的@ApiModel和@ApiModelProperty注解的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!