JAVA中@ApiModel和@ApiModelProperty注解实战代码

更新时间：2024年03月25日 10:03:27 作者：码农研究僧

这篇文章主要给大家介绍了关于JAVA中@ApiModel和@ApiModelProperty注解的相关资料,@ApiModel注解是用在接口相关的实体类上的注解,它主要是用来对使用该注解的接口相关的实体类添加额外的描述信息,常常和@ApiModelProperty注解配合使用,需要的朋友可以参考下

前言

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

}

总结

到此这篇关于JAVA中@ApiModel和@ApiModelProperty注解的文章就介绍到这了,更多相关JAVA中@ApiModel和@ApiModelProperty注解内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

java常见的字符串拼接方式总结
这篇文章主要为大家详细介绍了java中常见的字符串拼接方式,文中的示例代码讲解详细,具有一定的借鉴价值,感兴趣的小伙伴可以跟随小编一起学习一下
2023-09-09
SpringBoot项目中使用OkHttp获取IP地址的示例代码
OkHttp 是一个由 Square 开发的高效、现代的 HTTP 客户端库,用于 Android 和 Java 应用程序,它支持 HTTP/2 和 SPDY 等现代网络协议,并提供了多种功能和优化,本文给大家介绍了SpringBoot项目中如何获取IP地址,需要的朋友可以参考下
2024-08-08
使用 Java 开发 Gradle 插件的步骤
这篇文章主要介绍了使用 Java 开发 Gradle 插件的步骤，帮助大家更好的理解和学习使用Java，感兴趣的朋友可以了解下
2021-03-03
java中ThreadLocal的基本原理
本文讲解了java中ThreadLocal的一些基本原理，文中关于ThreadLocal的原理讲解的非常详细，感兴趣的朋友一起看看吧
2021-08-08
Java五种方法批量处理List元素的实现示例
本文主要介绍了Java五种方法批量处理List元素的实现示例,包括传统循环、函数式编程、Stream流、迭代器及第三方库,文中通过示例代码介绍的非常详细,需要的朋友们下面随着小编来一起学习学习吧
2025-05-05
为什么阿里要慎重使用ArrayList中的subList方法
这篇文章主要介绍了为什么要慎重使用ArrayList中的subList方法,subList是List接口中定义的一个方法，该方法主要用于返回一个集合中的一段、可以理解为截取一个集合中的部分元素，他的返回值也是一个List。,需要的朋友可以参考下
2019-06-06
idea与eclipse项目相互导入的过程(图文教程)
这篇文章主要介绍了idea与eclipse项目相互导入的过程，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
2020-03-03
Java里volatile关键字是什么意思
volatile具有synchronized关键字的“可见性”，但是没有synchronized关键字的“并发正确性”，也就是说不保证线程执行的有序性。这篇文章主要介绍了Java里volatile关键字是什么意思的相关资料,需要的朋友可以参考下
2016-11-11
mybatisplus selectOne查询,有数据,但返回为null问题
这篇文章主要介绍了mybatisplus selectOne查询,有数据,但返回为null问题,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
2023-11-11
java字符串比较获取字符串出现次数的示例
java获取一个字符串在整个字符串出现的次数，下面写出我的思路和二个实现方法，大家参考使用吧
2014-01-01