前言
在Java中，@ApiModel和@ApiModelProperty是Swagger框架（用于API文檔的工具）提供的注解，用于增強(qiáng)API文檔的生成和展示。這兩者搭配使用更佳
使用兩者注解，需導(dǎo)入swagger的依賴(lài)包：
<!-- 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>
主要作用：開(kāi)發(fā)者對(duì)API的模型和屬性進(jìn)行詳細(xì)的描述，以便生成清晰的API文檔。
1. @ApiModel注解
- @ApiModel注解用于對(duì)Java類(lèi)進(jìn)行標(biāo)注，表示這個(gè)類(lèi)是一個(gè)Swagger模型（Model）。通常用于描述一個(gè)數(shù)據(jù)對(duì)象或DTO（Data Transfer Object）。
示例代碼：
import io.swagger.annotations.ApiModel;
@ApiModel(description = "用戶(hù)信息")
public class User {
// 類(lèi)的屬性...
}
深入其源碼：
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)用的程序元素類(lèi)型，參數(shù)是一個(gè)ElementType數(shù)組。該源碼表示應(yīng)用在類(lèi)上 -
@Retention注解
用于指定自定義注解的生命周期，即注解在程序運(yùn)行時(shí)的保留策略。該源碼表示運(yùn)行時(shí) -
@Inherited注解
子類(lèi)會(huì)繼承該注解。默認(rèn)情況下，注解不會(huì)被子類(lèi)繼承。
對(duì)應(yīng)的屬性值為：
- value屬性：屬性值，也就是該實(shí)體類(lèi)的描述值，不寫(xiě)默認(rèn)為實(shí)體類(lèi)的名稱(chēng)，通常描述不清晰才需要value值
- description屬性：描述值，與value不同，該description為較長(zhǎng)描述值
- parent屬性：用于指定被注解類(lèi)的父類(lèi)
- discriminator屬性：多態(tài)情境區(qū)分多個(gè)子類(lèi)
- subTypes屬性：指定被注解類(lèi)的子類(lèi)
- reference屬性：提供對(duì)被注解類(lèi)的引用信息
2. @ApiModelProperty注解
-
@ApiModelProperty注解用于對(duì)Java類(lèi)的屬性進(jìn)行標(biāo)注，表示這個(gè)屬性是一個(gè)Swagger模型的屬性。它可以用于描述屬性的名稱(chēng)、說(shuō)明、數(shù)據(jù)類(lèi)型等信息
import io.swagger.annotations.ApiModelProperty;
public class User {
@ApiModelProperty(value = "用戶(hù)ID", example = "123")
private Long id;
@ApiModelProperty(value = "用戶(hù)名", 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屬性：
指定屬性或方法的名稱(chēng)，重寫(xiě)該屬性名字 -
allowableValues屬性：
指定屬性或方法的可接受值范圍。 -
access屬性：
指定屬性或方法的訪(fǎng)問(wèn)規(guī)則。 -
notes屬性：
提供對(duì)屬性或方法的額外說(shuō)明。 -
dataType屬性：
指定屬性或方法的數(shù)據(jù)類(lèi)型。 -
required屬性：
指定屬性或方法是否為必需。 -
position屬性：
指定屬性或方法在文檔中的位置。 -
hidden屬性：
指定屬性或方法是否應(yīng)該在文檔中隱藏。 -
example屬性：
提供屬性或方法的示例值。 -
readOnly屬性（已過(guò)時(shí)）：
指定屬性或方法是否為只讀。已過(guò)時(shí)，推薦使用 access 屬性。 -
accessMode屬性：
指定訪(fǎng)問(wèn)模式，可以是 AUTO、READ_ONLY 或 READ_WRITE。 -
reference屬性：
提供屬性或方法的引用信息。 -
allowEmptyValue屬性：
指定屬性或方法是否允許為空值。 -
extensions屬性：
指定屬性或方法的擴(kuò)展信息，支持一組擴(kuò)展屬性。 -
AccessMode枚舉：
屬性或方法的訪(fǎng)問(wèn)模式，包括 AUTO、READ_ONLY 和 READ_WRITE。
下面是一個(gè)簡(jiǎn)單的示例代碼：
import io.swagger.annotations.ApiModelProperty;
public class Example {
@ApiModelProperty(value = "用戶(hù)ID", example = "123", required = true)
private Long userId;
@ApiModelProperty(value = "用戶(hù)名", 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í)體類(lèi)如下：文章來(lái)源：http://www.zghlxwxcb.cn/news/detail-809500.html
@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è)備名稱(chēng)
*/
@ApiModelProperty(value = "設(shè)備名稱(chēng)")
private String equipmentName;
/**
* 設(shè)備機(jī)種
*/
@ApiModelProperty(value = "設(shè)備機(jī)種")
private String model;
/**
* 事故日期
*/
@ApiModelProperty(value = "事故日期")
private String dateTime;
/**
* 操作者
*/
@ApiModelProperty(value = "操作者")
private String operator;
/**
* 事故經(jīng)過(guò)
*/
@ApiModelProperty(value = "事故經(jīng)過(guò)")
private String content;
/**
* 損壞情況
*/
@ApiModelProperty(value = "損壞情況")
private String situation;
/**
* 事故原因
*/
@ApiModelProperty(value = "事故原因")
private String reason;
/**
* 事故類(lèi)別
*/
@ApiModelProperty(value = "事故類(lèi)別")
private String type;
/**
* 損失費(fèi)用
*/
@ApiModelProperty(value = "損失費(fèi)用")
private String expense;
/**
* 處理意見(jiàn)
*/
@ApiModelProperty(value = "處理意見(jiàn)")
private String opinion;
/**
* 主管技術(shù)員
*/
@ApiModelProperty(value = "主管技術(shù)員")
private String technician;
}
其前端vo類(lèi)別中的類(lèi)如下：文章來(lái)源地址http://www.zghlxwxcb.cn/news/detail-809500.html
@Data
@ApiModel(value = "AccidentRecordVO對(duì)象", description = "AccidentRecordVO對(duì)象")
public class AccidentRecordVO extends AccidentRecord {
private static final long serialVersionUID = 1L;
}
到了這里，關(guān)于詳解JAVA中的@ApiModel和@ApiModelProperty注解的文章就介紹完了。如果您還想了解更多內(nèi)容，請(qǐng)?jiān)谟疑辖撬阉鱐OY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！
