JAVA中@ApiModel和@ApiModelProperty注解實(shí)戰(zhàn)代碼

更新時(shí)間：2024年03月25日 10:03:27 作者：碼農(nóng)研究僧

這篇文章主要給大家介紹了關(guān)于JAVA中@ApiModel和@ApiModelProperty注解的相關(guān)資料,@ApiModel注解是用在接口相關(guān)的實(shí)體類上的注解,它主要是用來(lái)對(duì)使用該注解的接口相關(guān)的實(shí)體類添加額外的描述信息,常常和@ApiModelProperty注解配合使用,需要的朋友可以參考下

前言

在Java中，@ApiModel和@ApiModelProperty是Swagger框架（用于API文檔的工具）提供的注解，用于增強(qiáng)API文檔的生成和展示。這兩者搭配使用更佳

使用兩者注解，需導(dǎo)入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>

主要作用：開發(fā)者對(duì)API的模型和屬性進(jìn)行詳細(xì)的描述，以便生成清晰的API文檔。

1. @ApiModel注解

@ApiModel注解用于對(duì)Java類進(jìn)行標(biāo)注，表示這個(gè)類是一個(gè)Swagger模型（Model）。通常用于描述一個(gè)數(shù)據(jù)對(duì)象或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注解用于指定自定義注解可以應(yīng)用的程序元素類型，參數(shù)是一個(gè)ElementType數(shù)組。該源碼表示應(yīng)用在類上
@Retention注解用于指定自定義注解的生命周期，即注解在程序運(yùn)行時(shí)的保留策略。該源碼表示運(yùn)行時(shí)
@Inherited注解子類會(huì)繼承該注解。默認(rèn)情況下，注解不會(huì)被子類繼承。

對(duì)應(yīng)的屬性值為：

value屬性：屬性值，也就是該實(shí)體類的描述值，不寫默認(rèn)為實(shí)體類的名稱，通常描述不清晰才需要value值
description屬性：描述值，與value不同，該description為較長(zhǎng)描述值
parent屬性：用于指定被注解類的父類
discriminator屬性：多態(tài)情境區(qū)分多個(gè)子類
subTypes屬性：指定被注解類的子類
reference屬性：提供對(duì)被注解類的引用信息

2. @ApiModelProperty注解

@ApiModelProperty注解用于對(duì)Java類的屬性進(jìn)行標(biāo)注，表示這個(gè)屬性是一個(gè)Swagger模型的屬性。它可以用于描述屬性的名稱、說明、數(shù)據(jù)類型等信息

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屬性：
注解的默認(rèn)屬性，理解為注釋的作用
name屬性：
指定屬性或方法的名稱，重寫該屬性名字
allowableValues屬性：
指定屬性或方法的可接受值范圍。
access屬性：
指定屬性或方法的訪問規(guī)則。
notes屬性：提供對(duì)屬性或方法的額外說明。
dataType屬性：指定屬性或方法的數(shù)據(jù)類型。
required屬性：指定屬性或方法是否為必需。
position屬性：指定屬性或方法在文檔中的位置。
hidden屬性：指定屬性或方法是否應(yīng)該在文檔中隱藏。
example屬性：提供屬性或方法的示例值。
readOnly屬性（已過時(shí)）：指定屬性或方法是否為只讀。已過時(shí)，推薦使用 access 屬性。
accessMode屬性：指定訪問模式，可以是 AUTO、READ_ONLY 或 READ_WRITE。
reference屬性：提供屬性或方法的引用信息。
allowEmptyValue屬性：指定屬性或方法是否允許為空值。
extensions屬性：指定屬性或方法的擴(kuò)展信息，支持一組擴(kuò)展屬性。
AccessMode枚舉：屬性或方法的訪問模式，包括 AUTO、READ_ONLY 和 READ_WRITE。

下面是一個(gè)簡(jiǎn)單的示例代碼：

import io.swagger.annotations.ApiModelProperty;

public class Example {
    @ApiModelProperty(value = "用戶ID", example = "123", required = true)
    private Long userId;

    @ApiModelProperty(value = "用戶名", example = "碼農(nóng)研究僧", readOnly = true)
    public String getUsername() {
        return "碼農(nóng)研究僧";
    }
}

3. 實(shí)戰(zhàn)

比如應(yīng)用在技術(shù)行業(yè)的某個(gè)模塊，對(duì)應(yīng)數(shù)據(jù)庫(kù)中的entity實(shí)體類如下：

@Data
@TableName("equipment_accident_record")
@ApiModel(value = "AccidentRecord對(duì)象", description = "AccidentRecord對(duì)象")
public class AccidentRecord extends BaseEntity {

	private static final long serialVersionUID = 1L;

	/**
	* 設(shè)備編號(hào)
	*/
		@ApiModelProperty(value = "設(shè)備編號(hào)")
		private String equipmentNo;
	/**
	* 設(shè)備名稱
	*/
		@ApiModelProperty(value = "設(shè)備名稱")
		private String equipmentName;
	/**
	* 設(shè)備機(jī)種
	*/
		@ApiModelProperty(value = "設(shè)備機(jī)種")
		private String model;
	/**
	* 事故日期
	*/
		@ApiModelProperty(value = "事故日期")
		private String dateTime;
	/**
	* 操作者
	*/
		@ApiModelProperty(value = "操作者")
		private String operator;
	/**
	* 事故經(jīng)過
	*/
		@ApiModelProperty(value = "事故經(jīng)過")
		private String content;
	/**
	* 損壞情況
	*/
		@ApiModelProperty(value = "損壞情況")
		private String situation;
	/**
	* 事故原因
	*/
		@ApiModelProperty(value = "事故原因")
		private String reason;
	/**
	* 事故類別
	*/
		@ApiModelProperty(value = "事故類別")
		private String type;
	/**
	* 損失費(fèi)用
	*/
		@ApiModelProperty(value = "損失費(fèi)用")
		private String expense;
	/**
	* 處理意見
	*/
		@ApiModelProperty(value = "處理意見")
		private String opinion;
	/**
	* 主管技術(shù)員
	*/
		@ApiModelProperty(value = "主管技術(shù)員")
		private String technician;
}

其前端vo類別中的類如下：

@Data
@ApiModel(value = "AccidentRecordVO對(duì)象", description = "AccidentRecordVO對(duì)象")
public class AccidentRecordVO extends AccidentRecord {
	private static final long serialVersionUID = 1L;

}

總結(jié)

到此這篇關(guān)于JAVA中@ApiModel和@ApiModelProperty注解的文章就介紹到這了,更多相關(guān)JAVA中@ApiModel和@ApiModelProperty注解內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: