常用Swagger注解匯總

前言

??在實(shí)際編寫(xiě)后端代碼的過(guò)程中，我們可能經(jīng)常使用到 swagger 注解，但是會(huì)用不代表了解，你知道每個(gè)注解都有什么屬性嗎？你都用過(guò)這些屬性嗎？了解它們的作用嗎？本文在此帶大家總結(jié)一下常用的swagger注解，供大家學(xué)習(xí)理解。

控制器層

?

@Api

介紹

??此注解應(yīng)用于類、接口或者枚舉上，啟動(dòng)應(yīng)用時(shí)被標(biāo)注的類會(huì)掃描到 swagger 源中。默認(rèn)情況下，swagger 核心僅掃描帶有 @Api 注解的類而無(wú)視其他的源數(shù)據(jù) (例如：JAX-RS 端口、Serlvet 等等)

??不能標(biāo)注在方法上且一般不單獨(dú)使用，常見(jiàn)的做法是搭配 @ApiOperation 注解，作為業(yè)務(wù)接口類的說(shuō)明。

?

源碼

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 Api {String value() default "";String[] tags() default "";@Deprecated String description() default "";@Deprecated String basePath() default "";@Deprecated int position() default 0;String produces() default "";String consumes() default "";String protocols() default "";Authorization[] authorizations() default @Authorization(value = "");boolean hidden() default false;
}

?

屬性

??從源碼我們可以看到 @Api 注解除了已廢棄的3個(gè)，共有 7 個(gè)屬性，不過(guò)這里面只有下面這1個(gè)屬性比較常用：

1、tags (接口業(yè)務(wù)所屬分組)

這是一個(gè)用于控制 API 文檔標(biāo)簽的列表，標(biāo)簽可按資源或者其他標(biāo)識(shí)符對(duì)操作進(jìn)行分組。該屬性就是對(duì)實(shí)現(xiàn)相同業(yè)務(wù)功能的接口類做一個(gè)大致的分組，該分組中包括相同業(yè)務(wù)功能下的所有接口。

/*** swagger注解學(xué)習(xí)** @author 莪是男神* @date 2023/2/26 1:24*/
@Api(tags = "swagger注解學(xué)習(xí)")
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {/*** 測(cè)試方法*/@ApiOperation("測(cè)試方法")@GetMapping("/test")public R<Void> testApi(){System.out.println("Hello,world");return ok();}
}

說(shuō)完了常用的屬性，我們?cè)賮?lái)補(bǔ)充一下剩下的一些不常用屬性：

屬性	數(shù)據(jù)類型	默認(rèn)值	作用	示例	說(shuō)明
value	String	“”	接口分組說(shuō)明，在實(shí)際開(kāi)發(fā)中并不常用，且值會(huì)被 tags 屬性覆蓋	@Api(value = “操作名稱”) 或 @Api(“操作名稱”)	隱式地設(shè)置操作標(biāo)簽 (即操作名稱)，舊版本支持 (閱讀描述)。 在 Swagger 核心 1.3.X 的版本中，此屬性僅作為主機(jī) API 資源的聲明路徑，到 1.5.X 版本之后就不再關(guān)聯(lián)了。
hidden	boolean	false	隱藏該分組下的所有接口。此外要注意的是，接口的顯示隱藏應(yīng)該根據(jù)特定的安全策略和特定客戶需求來(lái)確定	@Api(hidden = true)	隱藏資源下的操作。此屬性的值默認(rèn)為 false，當(dāng)設(shè)置為 true 時(shí)，該分組的所有操作都會(huì)在 swagger 文檔中被隱藏，適用于接口暫時(shí)不需要使用時(shí)的情況。
produces	String	“”	指定的content-type 的輸出	@Api(produces=“application/json”)	??此屬性在新版本的 swagger 中已不再使用，僅用于向下兼容舊版本。對(duì)應(yīng)此資源下操作生成的字段。 獲取逗號(hào)分割的內(nèi)容類型值，例如，“application/json”，“application/xml” 將會(huì)提醒操作生成 JSON 或 XML 輸出。 對(duì)于 JAX-RS 資源，如果存在將會(huì)自動(dòng)獲取 @Produces 注解的值，同時(shí)也可用于覆蓋 Swapper 文檔的 @Produces 的值。
consumes	String	“”	指定的content-type 的輸入	@Api(consumes=“application/xml”)	對(duì)應(yīng)此資源下操作消費(fèi)的字段。 獲取逗號(hào)分割的內(nèi)容類型值。例如例如，“application/json”，“application/xml” 將會(huì)提醒操作接收 JSON 或 XML 輸入。 對(duì)于 JAX-RS 資源，如果存在將會(huì)自動(dòng)獲取 @Consumes 注解的值，同時(shí)也可用于覆蓋 Swagger 文檔的 @Consumes 的值。
protocols	String	“”	網(wǎng)絡(luò)請(qǐng)求協(xié)議	@Api(protocols = “http,https”)	設(shè)置此資源下操作的指定協(xié)議(或方案)。 以逗號(hào)分割可用的協(xié)議值，可用值：http, https, ws, wss
authorizations	Authorization[]	@Authorization(value = “”)	規(guī)定接口分組的授權(quán)方案		對(duì)應(yīng)操作對(duì)象的安全字段。 獲取此資源下操作的授權(quán) (安全需求) 列表，這可能會(huì)被特定的操作覆蓋。

?

@ApiOperation

介紹

??@ApiOperation 注解可應(yīng)用于方法或類上，通常標(biāo)注在方法上作為業(yè)務(wù)接口的名稱，描述其操作或者描述針對(duì)于特定路徑的 HTTP 方法。默認(rèn)情況下，具有相同效果的操作被分組在一個(gè)單獨(dú)的操作對(duì)象中，而 HTTP 方法和路徑的組合將會(huì)創(chuàng)建一個(gè)獨(dú)一無(wú)二的操作。此外，此注解提供了豐富的屬性來(lái)允許我們自定義接口的描述信息，包括接口名稱和所屬分組等。

?

源碼

package io.swagger.annotations;import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiOperation {String value();String notes() default "";String[] tags() default "";Class<?> response() default Void.class;String responseContainer() default "";String responseReference() default "";String httpMethod() default "";@Deprecated int position() default 0;String nickname() default "";String produces() default "";String consumes() default "";String protocols() default "";Authorization[] authorizations() default @Authorization(value = "");boolean hidden() default false;ResponseHeader[] responseHeaders() default @ResponseHeader(name = "", response = Void.class);int code() default 200;Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));boolean ignoreJsonView() default false;
}

?

屬性

??從源碼我們可以看到 @ApiOperation 注解除了已廢棄的1個(gè)，共有 17 個(gè)屬性。不過(guò)這里面只有以下 2 個(gè)屬性比較常用：

?

1、value (接口名稱)

對(duì)應(yīng)操作的摘要字段。此屬性提供接口的簡(jiǎn)要描述（即接口說(shuō)明），最多 120 個(gè)字符或者少于 Swagger-UI 頁(yè)面可展示的。

/*** swagger注解學(xué)習(xí)** @author 莪是男神* @date 2023/2/26 1:24*/
@Api(tags = "swagger注解學(xué)習(xí)")
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {/*** 獲取信息*/@ApiOperation("獲取信息")@GetMapping("/getInfo")public R<Integer> getInfo() {int i = 1;return R.ok(i);}
}

2、notes (接口描述)

對(duì)應(yīng)操作的詳情字段。這是一段冗長(zhǎng)的操作描述，沒(méi)有字?jǐn)?shù)限制，通常適用于當(dāng) value 屬性無(wú)法解釋清楚時(shí)對(duì)接口操作的補(bǔ)充說(shuō)明。

/*** swagger注解學(xué)習(xí)** @author 莪是男神* @date 2023/2/26 1:24*/
@Api(tags = "swagger注解學(xué)習(xí)")
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {/*** 獲取信息*/@ApiOperation(value = "獲取信息", notes = "用于獲取信息的接口")@GetMapping("/getInfo")public R<Integer> getInfo() {int i = 1;return R.ok(i);}
}

說(shuō)完了常用的屬性，我們?cè)賮?lái)補(bǔ)充一下剩下的一些不常用屬性：

屬性	數(shù)據(jù)類型	默認(rèn)值	作用	示例	說(shuō)明
tags	String[]	“”	定義接口分組，如果一個(gè)接口涉及到多個(gè)業(yè)務(wù)場(chǎng)景，那這個(gè)時(shí)候需要我們對(duì)接口進(jìn)行多個(gè)分組	@ApiOperation(tags={“測(cè)試標(biāo)簽1”, “測(cè)試標(biāo)簽2”})	一個(gè)用于控制 API 文檔標(biāo)簽的列表，標(biāo)簽可按資源或者其他標(biāo)識(shí)符對(duì)操作進(jìn)行分組。此外，操作的 Api 注解的 value 或者 tags 屬性將會(huì)覆蓋其單個(gè)的非空值。
response	Class<?>	Void.class	指定響應(yīng)的數(shù)據(jù)類型	@ApiOperation(response = ReturnResult.class)	操作返回的響應(yīng)類型 在 JAX-RS 應(yīng)用程序中，方法的返回類型將會(huì)自動(dòng)使用，除了 javax.ws.core.Response。而在其他情況下，操作返回類型默認(rèn)為 void ，因?yàn)椴恢缹?shí)際的響應(yīng)類型。 設(shè)置此屬性將會(huì)覆蓋任何自動(dòng)派生的數(shù)據(jù)類型 如果被用到的值是用一個(gè)類 (Integer、Long) 的基本數(shù)據(jù)類型表示的，那么則會(huì)使用相應(yīng)的基本數(shù)據(jù)類型響應(yīng)
responseContainer	String	“”	包裝HTTP響應(yīng)的容器類型	@ApiOperation(responseContainer= “List”)	聲明一個(gè)包裝響應(yīng)的容器，有效值只有 “List”、“Set”、“Map”，其他值都會(huì)被忽略。
responseReference	String	“”	支持遠(yuǎn)程調(diào)用的響應(yīng)數(shù)據(jù)類型，比 response 屬性優(yōu)先級(jí)更高	@ApiOperation(responseReference= “java.lang.Integer”)	指定一個(gè)響應(yīng)類型的引用。此引用可以是本地的或者遠(yuǎn)程的并且將按原樣使用，覆任何的指定的 response 屬性類
httpMethod	String	“”	接口使用的HTTP方法	@ApiOperation(httpMethod= “GET”)	對(duì)應(yīng)使用的HTTP方法 如果是無(wú)狀態(tài)的，在 JAX-RS 應(yīng)用程序中，下列 JAX-RS 注解將會(huì)被掃描且使用：@GET、@HEAD、@POST、@PUT、@DELETE 和 @OPTIONS。注意即使它不是 JAX-RS規(guī)范指定的部分（也可以被掃描并使用），如果您創(chuàng)建并使用 @PATCH 注解，它也會(huì)被解析并使用，如果設(shè)置了此屬性，那么將會(huì)覆蓋 JAX-RS 注解。 對(duì)于 Sevlet 而言，您必須手動(dòng)指定 HTTP 方法，可接收的值是 “GET”、“HEAD”、“POST”、“PUT”、“DELETE”、“GET”、“DELETE” 和 “PATCH”。
nickname	String	“”	接口別名，方便前后端溝通使用，沒(méi)有其他含義	@ApiOperation(nickname= “測(cè)試別名”)	對(duì)應(yīng)操作 ID 字段。 此操作 ID 被用于第三方工具唯一識(shí)別此操作的手段，在 Swagger 2.0 中，這不是必填參數(shù)，如果不提供值可以為空。
produces	String	“”	指定的content-type 的輸出	@ApiOperation(produces=“application/json”)	對(duì)應(yīng)此資源下操作生成的字段。 獲取逗號(hào)分割的內(nèi)容類型值，例如，“application/json”，“application/xml” 將會(huì)提醒操作生成 JSON 或 XML 輸出。 對(duì)于 JAX-RS 資源，如果存在將會(huì)自動(dòng)獲取 @Produces 注解的值，同時(shí)也可用于覆蓋 Swapper 文檔的 @Produces 的值。
consumes	String	“”	指定的content-type 的輸入	@ApiOperation(consumes=“application/xml”)	對(duì)應(yīng)此資源下操作消費(fèi)的字段。 獲取逗號(hào)分割的內(nèi)容類型值。例如例如，“application/json”，“application/xml” 將會(huì)提醒操作接收 JSON 或 XML 輸入。 對(duì)于 JAX-RS 資源，如果存在將會(huì)自動(dòng)獲取 @Consumes 注解的值，同時(shí)也可用于覆蓋 Swagger 文檔的 @Consumes 的值。
protocols	String	“”	網(wǎng)絡(luò)請(qǐng)求協(xié)議	@ApiOperation(protocols = “http,https”)	設(shè)置此資源下操作的指定協(xié)議(或方案)。 以逗號(hào)分割可用的協(xié)議值，可用值：http, https, ws, wss
authorizations	Authorization[]	@Authorization(value = “”)	定義接口的授權(quán)方案		對(duì)應(yīng)操作對(duì)象的安全字段。 獲取此資源下操作的授權(quán) (安全需求) 列表，這可能會(huì)被特定的操作覆蓋。
hidden	boolean	false	此屬性用于隱藏接口，但要注意的是，接口的顯示隱藏應(yīng)該根據(jù)特定的安全策略和特定客戶需求來(lái)	@ApiOperation(hidden= true)	操作列表中隱藏此操作
responseHeaders	ResponseHeader[]	@ResponseHeader(name = “”, response = Void.class)	HTTP響應(yīng)頭參數(shù)	@ApiOperation(responseHeaders = {@ResponseHeader(name = “auth”, response = String.class)})	在響應(yīng)中可能提供的響應(yīng)頭列表
code	int	200	HTTP狀態(tài)碼，swagger自動(dòng)生成，一般不用設(shè)置	@ApiOperation(code = 404)	HTTP 響應(yīng)狀態(tài)碼，其值應(yīng)該是正式 HTTP 狀態(tài)碼定義的其中之一
extensions	Extension[]	@Extension(properties = @ExtensionProperty(name = “”, value = “”))	可選的擴(kuò)展屬性數(shù)組	@ApiOperation(extensions = @Extension(properties = @ExtensionProperty(name = “key”, value = “value”)))	可選的擴(kuò)展屬性數(shù)組
ignoreJsonView	boolean	false	忽略JsonView 注解	@ApiOperation(ignoreJsonView = true)	當(dāng)解析操作和類型時(shí)忽略 @JsonView 注解，用于向后兼容

?

@ApiImplicitParam

前言

??此注解只能標(biāo)注在方法上，代表了方法中的一個(gè)獨(dú)立的參數(shù)，如果方法有多個(gè)參數(shù)，可以和 @ApiImplicitParams 注解搭配使用。

??當(dāng) ApiParam 注解綁定了一個(gè) JAX-RS 的參數(shù)、方法、或者字段時(shí)，它允許您以微調(diào)的方式手動(dòng)定義一個(gè)參數(shù)。這是當(dāng)使用 Servlet 或者其他非 JAX-RS 環(huán)境時(shí)定義參數(shù)的唯一方法。

??此注解和 @ApiParam 注解一樣都可以應(yīng)用于方法參數(shù)上，不過(guò) @ApiParam 更適用于參數(shù)不是包裝類或者 String 的情況，此時(shí)配合 @ApiModel和@ApiModelProperty 再好不過(guò)，而 @ApiImplicitParam 通常適用于方法中有單個(gè)或多個(gè)參數(shù)且不是通過(guò)一個(gè)類去接收所有參數(shù)的情況，這時(shí)候使用它，非常合適。

?

源碼

package io.swagger.annotations;import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiImplicitParam {String name() default "";String value() default "";String defaultValue() default "";String allowableValues() default "";boolean required() default false;String access() default "";boolean allowMultiple() default false;String dataType() default "";Class<?> dataTypeClass() default Void.class;String paramType() default "";String example() default "";Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));String type() default "";String format() default "";boolean allowEmptyValue() default false;boolean readOnly() default false;String collectionFormat() default "";
}

從源碼我們可以看到 @ApiImplicitParam 注解共有 17 個(gè)屬性。不過(guò)這里面只有以下 2 個(gè)屬性比較常用：

1、name (參數(shù)名稱)

此屬性表示參數(shù)的名稱。為了保持適當(dāng)?shù)?Swagger 功能，當(dāng)根據(jù) parameType() (指參數(shù)類型) 命名參數(shù)時(shí)，請(qǐng)遵循以下規(guī)則：

(1)、如果參數(shù)類型是路徑，其名稱應(yīng)當(dāng)是路徑中所關(guān)聯(lián)的那部分 (相對(duì)路徑)

(2)、對(duì)于所有的其他情況，其名稱應(yīng)當(dāng)是當(dāng)前應(yīng)用程序希望接收的

/*** swagger注解學(xué)習(xí)** @author 莪是男神* @date 2023/2/26 1:24*/
@Api(tags = "swagger注解學(xué)習(xí)")
@Slf4j
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {/*** 打印消息** @param msg 待打印的消息*/@ApiOperation("打印消息")@ApiImplicitParams({@ApiImplicitParam(name = "msg"),@ApiImplicitParam(name = "author")})@GetMapping("/print")public R<String> printMsg(String msg, String author) {log.info("這是您發(fā)送的消息：{}", msg);return R.ok(msg);}
}

2、value (參數(shù)說(shuō)明)

這是一個(gè)簡(jiǎn)短的參數(shù)描述。

/*** swagger注解學(xué)習(xí)** @author 莪是男神* @date 2023/2/26 1:24*/
@Api(tags = "swagger注解學(xué)習(xí)")
@Slf4j
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {/*** 展示方法*/@ApiOperation("展示方法")@ApiImplicitParam(name = "request", value = "HTTP請(qǐng)求")@GetMapping("/show")public R<String> show(HttpServletRequest request) {String method = request.getMethod();return R.ok(method);}
}

3、allowableValues (參數(shù)范圍)

限制此參數(shù)接收的值，以下有三種方法可以描述請(qǐng)求參數(shù)的范圍：

(1)、設(shè)置一個(gè)值的列表，提供一個(gè)以逗號(hào)分割的列表。例如：first, second, third。

(2)、設(shè)置一個(gè)值的范圍，以 “range” 開(kāi)始這個(gè)值，周圍用方括號(hào)表示最小值和最大值，或使用圓括號(hào)表示獨(dú)占的最小值和最大值。例如：range[1, 5]、range(1, 5), range[1, 5)。注意，此屬性需要配合 dataTypeClass 屬性才有用，單獨(dú)設(shè)置沒(méi)有效果

/*** swagger注解學(xué)習(xí)** @author 莪是男神* @date 2023/2/26 1:24*/
@Api(tags = "swagger注解學(xué)習(xí)")
@Slf4j
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {/*** 獲取隨機(jī)數(shù)* @param seed 隨機(jī)數(shù)種子*/@ApiOperation("獲取隨機(jī)數(shù)")@ApiImplicitParam(name = "seed", value = "隨機(jī)數(shù)種子", allowableValues = "1,2,3,4,5,6,7,8,9,10", dataTypeClass = Integer.class)@GetMapping("/random")public R<Integer> random(Integer seed) {Random random = new Random(seed);int i = random.nextInt();return R.ok(i);}}

當(dāng)使用swagger文檔調(diào)用接口也可以看到：

4、required (參數(shù)是否必填)

指定參數(shù)為必要的還是非必要的，如果當(dāng)前參數(shù)為path參數(shù)，應(yīng)當(dāng)設(shè)置此屬性為true。

/*** swagger注解學(xué)習(xí)** @author 莪是男神* @date 2023/2/26 1:24*/
@Api(tags = "swagger注解學(xué)習(xí)")
@Slf4j
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {/*** 獲取用戶信息*/@ApiOperation("獲取用戶信息")@ApiImplicitParam(name = "userId", value = "用戶ID", required = true)@GetMapping("/info/{userId}")public R<Void> getUserInfo(@PathVariable("userId") Long userId) {return ok();}
}

說(shuō)完了常用的屬性，我們?cè)賮?lái)補(bǔ)充一下剩下的一些不常用屬性：

屬性	數(shù)據(jù)類型	默認(rèn)值	概述	示例	說(shuō)明
defaultValue	String	“”	參數(shù)默認(rèn)值	@ApiImplicitParam(defaultValue = “1”)	描述參數(shù)的默認(rèn)值，當(dāng)請(qǐng)求參數(shù)中有分頁(yè)參數(shù)或有需要設(shè)置默認(rèn)值的參數(shù)，可設(shè)置此屬性
access	String	“”			允許API文檔過(guò)濾參數(shù)，更多細(xì)節(jié)請(qǐng)查看 SwaggerSpecFilter 類
allowMultiple	String	“”	此參數(shù)是否能接受多個(gè)值	@ApiImplicitParam(allowMultiple= true)	指定此參數(shù)是否能在各種情況下能夠接收多個(gè)值，默認(rèn)值為false
dataType	String	“”	數(shù)據(jù)類型	@ApiImplicitParam(dataType=“int”)	參數(shù)的數(shù)據(jù)類型，可以是類名或者基本數(shù)據(jù)類型
dataTypeClass	Class<?>	Void.class	class 類型，此屬性不定義的話程序可能會(huì)有警告	@ApiImplicitParam(dataTypeClass = String.class)	參數(shù)的 class 類型，如果此屬性指定了值的話會(huì)覆蓋 dataType 提供的
paramType	String	“”	參數(shù)的HTTP參數(shù)類型	@ApiImplicitParam(param=“query”)	參數(shù)的參數(shù)類型，有效值是 path、query、body、header 或者 form，其他值會(huì)被忽略
example	String	“”	參數(shù)示例	@ApiImplicitParam(example=“1”)	一個(gè)非 body 類型的單獨(dú)參數(shù)示例
examples	Example	@Example(value = @ExampleProperty(mediaType = “”, value = “”))	參數(shù)示例集合		參數(shù)示例，僅適用于body參數(shù)
type	String	“”	參數(shù)類型	@ApiImplicitParam(type = “int”)	添加了覆蓋所檢測(cè)到的類型的能力
format	String	“”	參數(shù)的自定義格式	@ApiImplicitParam(type = “integer”, format=“int64”)	添加了提供自定義格式的能力
allowEmptyValue	boolean	false	是否允許傳遞空值	@ApiImplicitParam(allowEmptyValue=true)	添加了設(shè)置空值格式的能力
readOnly	boolean	false	是否只讀	@ApiImplicitParam(readOnly=true)	添加了被認(rèn)定為只讀的能力
collectionFormat	String	“”	集合的格式		添加了使用數(shù)組類型覆蓋集合格式的能力

?

@ApiImplicitParams

介紹

??此注解是 @ApiImplicitParam 注解的包裝器，單獨(dú)使用沒(méi)有意義，必須和 @ApiImplicitParam 進(jìn)行搭配，當(dāng)接口方法中有一個(gè)及以上的參數(shù)時(shí)可以使用。

?

源碼

package io.swagger.annotations;import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiImplicitParams {ApiImplicitParam[] value();
}

從源碼我們可以看到 @ApiImplicitParams 注解有且只有一個(gè)常用的屬性：

1、value（注解列表）

一個(gè)用于API操作的 ApiImplicitParam 注解的列表

/*** swagger注解學(xué)習(xí)** @author 莪是男神* @date 2023/2/26 1:24*/
@Api(tags = "swagger注解學(xué)習(xí)")
@Slf4j
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {/*** 登錄*/@ApiOperation("登錄")@ApiImplicitParams({@ApiImplicitParam(name = "username", value = "用戶名", required = true),@ApiImplicitParam(name = "password", value = "密碼", required = true)})@GetMapping("/login")public R<Void> login(String username, String password) {return ok();}
}

@ApiParam

介紹

??@ApiParam 注解作用在接口方法上面，以及接口方法中的參數(shù)位置的注解，其主要作用是用來(lái)給接口中的參數(shù)定義相關(guān)的參數(shù)說(shuō)明，旨在幫助相關(guān)技術(shù)人員理解接口中每個(gè)參數(shù)的含義。注意，此注解只能在 JAX-RS 1.x/2.x 注解的組合中使用，和 @ApiImplicitParam 注解同樣的是，都可以標(biāo)注在方法上，對(duì)方法的參數(shù)進(jìn)行解釋說(shuō)明。唯一的不同點(diǎn)是，@ApiImplicitParam 注解比 @ApiParam 更適合標(biāo)注在包裝類或 Spring 類上，且配合 @ApiImplicitParams 可以做到支持多個(gè)參數(shù)，而 @ApiParam 只能有一個(gè)。

?

源碼

package io.swagger.annotations;import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiParam {String name() default "";String value() default "";String defaultValue() default "";String allowableValues() default "";boolean required() default false;String access() default "";boolean allowMultiple() default false;boolean hidden() default false;String example() default "";Example examples() default @Example(value = @ExampleProperty(mediaType = "", value = ""));String type() default "";String format() default "";boolean allowEmptyValue() default false;boolean readOnly() default false;String collectionFormat() default "";
}

?

屬性

從源碼我們可以看到 @ApiParam 注解共有 15 個(gè)屬性。不過(guò)這里面只有以下 2 個(gè)屬性比較常用：

1、name（參數(shù)名稱）

此屬性代表了參數(shù)的名稱，值可能來(lái)自字段、方法或參數(shù)名稱，應(yīng)當(dāng)重寫(xiě)它。

/*** swagger注解學(xué)習(xí)** @author 莪是男神* @date 2023/2/26 1:24*/
@Api(tags = "swagger注解學(xué)習(xí)")
@Slf4j
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {/*** 打印消息* @param msg 消息*/@ApiOperation("打印消息")@ApiParam(name = "msg")@GetMapping("/printMsg")public R<Void> printMsg(String msg) {System.out.println("msg = " + msg);return ok();}
}

2、value（參數(shù)說(shuō)明）

這是一段簡(jiǎn)短的參數(shù)描述。

/*** swagger注解學(xué)習(xí)** @author 莪是男神* @date 2023/2/26 1:24*/
@Api(tags = "swagger注解學(xué)習(xí)")
@Slf4j
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {/*** 獲取信息* @param msg 消息*/@ApiOperation("獲取信息")@ApiParam(name = "msg", value = "消息")@GetMapping("/getInfo")public R<String> getInfo(String msg) {String info = msg + "Hello,world";return ok(info);}}

3、required (是否必填)

指定請(qǐng)求參數(shù)是否必填，假如當(dāng)前參數(shù)類型為path則必須設(shè)置此屬性。

/*** swagger注解學(xué)習(xí)** @author 莪是男神* @date 2023/2/26 1:24*/
@Api(tags = "swagger注解學(xué)習(xí)")
@Slf4j
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {/*** 獲取信息* @param msg 消息*/@ApiOperation("獲取信息")@ApiParam(name = "msg", value = "消息", required = true)@GetMapping("/getInfo")public R<String> getInfo(String msg) {String info = msg + "Hello,world";return ok(info);}}

說(shuō)完了常用的屬性，我們?cè)賮?lái)補(bǔ)充一下剩下的一些不常用屬性：

屬性	數(shù)據(jù)類型	默認(rèn)值	概述	示例	說(shuō)明
defaultValue	String	“”	參數(shù)的默認(rèn)值	@ApiParam(defaultValue = “1”)	描述參數(shù)的默認(rèn)值，當(dāng)請(qǐng)求參數(shù)中有分頁(yè)參數(shù)或有需要設(shè)置默認(rèn)值的參數(shù)，可設(shè)置此屬性
access	String	“”			允許API文檔過(guò)濾參數(shù)，更多細(xì)節(jié)請(qǐng)查看 SwaggerSpecFilter 類
allowMultiple	boolean	false	此參數(shù)是否能接受多個(gè)值	@ApiParam(allowMultiple= true)	指定此參數(shù)是否能在各種情況下能夠接收多個(gè)值，默認(rèn)值為false
hidden	boolean	false	控制參數(shù)的隱藏或顯示	@ApiParam(hidden = true)	隱藏參數(shù)列表中的此參數(shù)
example	String	“”	參數(shù)示例	@ApiParam(example=“1”)	一個(gè)非 body 類型的單獨(dú)參數(shù)示例
examples	Example	@Example(value = @ExampleProperty(mediaType = “”, value = “”))	參數(shù)示例集合		參數(shù)示例，僅適用于body參數(shù)
type	String	“”	參數(shù)類型	@ApiParam(type = “int”)	添加了覆蓋所檢測(cè)到的類型的能力
format	String	“”	參數(shù)格式	@ApiParam(type = “integer”, format=“int64”)	添加了提供自定義格式的能力
allowEmptyValue	boolean	false	是否允許傳遞空值	@ApiParam(allowEmptyValue=true)	添加了設(shè)置空值格式的能力
readOnly	boolean	false	是否只讀	@ApiParam(readOnly=true)	添加了被認(rèn)定為只讀的能力
collectionFormat	String	“”	集合的格式		添加了使用數(shù)組類型覆蓋集合格式的能力

Tips

??你知道嗎？Spring 框架在控制器層面也提供了一些有關(guān)于請(qǐng)求參數(shù)的注解，通常swagger注解也會(huì)配合這些注解一起使用，了解這些注解對(duì)你百利而無(wú)一害。

注解	說(shuō)明
@RequestParam	Spring的請(qǐng)求參數(shù)注解，可以標(biāo)注在方法參數(shù)上，如果前后端參數(shù)不對(duì)應(yīng)的話，可以使用此注解進(jìn)行參數(shù)綁定
@RequestBody	將當(dāng)前參數(shù)綁定為請(qǐng)求主體，POST、PUT方法中常用
@RequestHeader	如果方法需要接受請(qǐng)求頭參數(shù)，那么可以使用此注解，表示當(dāng)前參數(shù)是一個(gè)請(qǐng)求頭參數(shù)
@RequestAttribute	將當(dāng)前參數(shù)綁定為HTTP請(qǐng)求中的一個(gè)屬性，通過(guò) request.getAttribute() 方法可獲取屬性值
@RequestPart	可以將 “multipart/form-data” 請(qǐng)求的參數(shù)和方法參數(shù)進(jìn)行相關(guān)聯(lián)

?

實(shí)體層

@ApiModel

介紹

??為模型或視圖對(duì)象提供額外的 swagger 說(shuō)明信息， 被標(biāo)注的類將會(huì) “ 自我介紹 ”，因?yàn)樗鼈冊(cè)诓僮髦斜挥米黝愋?#xff0c;不過(guò)程序員們更喜歡著眼于類的內(nèi)部結(jié)構(gòu)。此注解是作用在接口相關(guān)的實(shí)體類上的注解，用來(lái)對(duì)該接口的相關(guān)實(shí)體類添加額外的描述信息，一般和 @ApiModelProperty 注解配合使用。

?

源碼

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 "";
}

?

屬性

從源碼我們可以看到 @ApiModel 注解共有 6 個(gè)屬性，不過(guò)這里面只有下面這1個(gè)屬性比較常用：

1、value (模型描述)

為模型提供一個(gè)替代名稱（替代類名），如果沒(méi)有標(biāo)注此屬性，默認(rèn)情況下使用類名。

實(shí)體層

/*** 用戶對(duì)象** @author 莪是男神*/
@Data
@ApiModel("用戶信息")
public class UserInfo implements Serializable {private static final long serialVersionUID = 1L;/** 用戶ID */private Long userId;/** 部門ID */private Long deptId;/** 用戶賬號(hào) */private String userName;/** 用戶昵稱 */private String nickName;/** 用戶郵箱 */private String email;/** 手機(jī)號(hào)碼 */private String phonenumber;/** 用戶性別 */private String sex;/** 用戶頭像 */private String avatar;/** 密碼 */private String password;/** 帳號(hào)狀態(tài)（0正常 1停用） */private String status;/** 刪除標(biāo)志（0代表存在 2代表刪除） */private String delFlag;/** 最后登錄IP */private String loginIp;/** 最后登錄時(shí)間 */private Date loginDate;}

控制器層

/*** swagger注解學(xué)習(xí)** @author 莪是男神* @date 2023/2/26 1:24*/
@Api(tags = "swagger注解學(xué)習(xí)")
@Slf4j
@Anonymous
@RestController
@RequestMapping("/annotationLearn")
public class AnnotationLearnController extends BaseController {/*** 獲取用戶信息** @param userId 用戶ID*/@ApiOperation("獲取用戶")@ApiImplicitParam(name = "userId", value = "用戶ID", dataTypeClass = Long.class, paramType = "query", required = true)@GetMapping("/info")public R<UserInfo> getInfo(Long userId) {UserInfo userInfo = new UserInfo();userInfo.setUserId(userId);return R.ok(userInfo);}}

說(shuō)完了常用的屬性，我們?cè)賮?lái)補(bǔ)充一下剩下的一些不常用屬性：

屬性	數(shù)據(jù)類型	默認(rèn)值	概述	示例	說(shuō)明
description	String	“”	類描述。 在實(shí)際開(kāi)發(fā)中，此屬性一般會(huì)配合 value 屬性進(jìn)行使用，很少會(huì)出現(xiàn)只是用 value 屬性而不使用 description 屬性的情況。	@ApiMode(description = “系統(tǒng)用戶的詳細(xì)信息”)	為此模型提供一個(gè)冗長(zhǎng)的描述
parent	Class<?>	Void.class	描述類的繼承關(guān)系	@ApiModel(parent = Object.class)	為模型提供一個(gè)父類，允許描述其中的繼承關(guān)系
discriminator	String	“”	實(shí)現(xiàn)類的多態(tài)性	@ApiModel(discriminator= “userId”)	此屬性用于支持模型繼承以及多態(tài)性。 其值用作鑒別器的字段名稱，基于這個(gè)字段，可以斷言需要使用哪種子類型
subTypes	Class<?>[]	{}	展示繼承接口相關(guān)實(shí)體類class的子類	@ApiModel(subTypes={String.class})	一個(gè)繼承此模型的子類數(shù)組
reference	String	“”	實(shí)體類的類型引用		指定對(duì)應(yīng)類型定義的引用，并覆蓋所指定的任何其他的元數(shù)據(jù)

?

@ApiModelProperty

介紹

??此注解可標(biāo)注在方法或字段上，通常配合 @ApiModel 注解一起使用，用于添加或操作接口相關(guān)實(shí)體類的字段信息

?

源碼

package io.swagger.annotations;import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;@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 "";@Deprecatedboolean readOnly() default false;AccessMode accessMode() default AccessMode.AUTO;String reference() default "";boolean allowEmptyValue() default false;Extension[] extensions() default @Extension(properties = @ExtensionProperty(name = "", value = ""));enum AccessMode {AUTO,READ_ONLY,READ_WRITE;}
}

?

屬性

??從源碼我們可以看到 @ApiModelProperty 注解除了已廢棄的1個(gè)，共有 14 個(gè)屬性和一個(gè)枚舉，不過(guò)這里面只有下面這1個(gè)屬性比較常用：

1、value (字段描述)

一段簡(jiǎn)短的字段描述。

/*** 用戶對(duì)象** @author 莪是男神*/
@Data
@ApiModel(value = "用戶信息")
public class UserInfo {private static final long serialVersionUID = 1L;/** 用戶ID */@ApiModelProperty("用戶ID")private Long userId;/** 部門ID */@ApiModelProperty("部門ID")private Long deptId;/** 用戶賬號(hào) */@ApiModelProperty("用戶賬號(hào)")private String userName;/** 用戶昵稱 */@ApiModelProperty("用戶昵稱")private String nickName;/** 用戶郵箱 */@ApiModelProperty("用戶郵箱")private String email;/** 手機(jī)號(hào)碼 */@ApiModelProperty("手機(jī)號(hào)碼")private String phonenumber;/** 用戶性別 */@ApiModelProperty("用戶性別")private String sex;/** 用戶頭像 */@ApiModelProperty("用戶頭像")private String avatar;/** 密碼 */@ApiModelProperty("密碼")private String password;/** 帳號(hào)狀態(tài)（0正常 1停用） */@ApiModelProperty("帳號(hào)狀態(tài)（0正常 1停用）")private String status;/** 刪除標(biāo)志（0代表存在 2代表刪除） */@ApiModelProperty("刪除標(biāo)志（0代表存在 2代表刪除）")private String delFlag;/** 最后登錄IP */@ApiModelProperty("最后登錄IP")private String loginIp;/** 最后登錄時(shí)間 */@ApiModelProperty("最后登錄時(shí)間")private Date loginDate;}

說(shuō)完了常用的屬性，我們?cè)賮?lái)補(bǔ)充一下剩下的一些不常用屬性：

屬性	數(shù)據(jù)類型	默認(rèn)值	概述	示例	說(shuō)明
name	String	“”	字段的名稱	@ApiModelProperty(name = “userId”)	允許覆蓋屬性的名稱
defaultValue	String	“”	字段的默認(rèn)值	@ApiModelProperty(defaultValue = “1”)	描述屬性的默認(rèn)值，當(dāng)屬性需要設(shè)置默認(rèn)值時(shí)，可設(shè)置此屬性
access	String	“”			允許API文檔過(guò)濾參數(shù)，更多細(xì)節(jié)請(qǐng)查看 SwaggerSpecFilter 類
notes	String	“”	暫時(shí)沒(méi)用	@ApiModelProperty(notes= “暫時(shí)沒(méi)用”)	注解的擴(kuò)展屬性，當(dāng)前未使用。
dataType	String	“”	描述字段的數(shù)據(jù)類型	@ApiModelProperty(dataType=“int”)	這個(gè)屬性描述字段的數(shù)據(jù)類型，其值可以是對(duì)象或者是基本數(shù)據(jù)類型，而且會(huì)覆蓋從類屬性中讀取的數(shù)據(jù)類型。
required	boolean	false	是否必填	@ApiModelProperty(required=true)	指定字段為必要的還是非必要的
position	int	0	指定字段在swagger文檔中的顯示順序	@ApiModelProperty(position= 1)	允許排序類的字段
hidden	boolean	false	隱藏類的字段	@ApiModelProperty(hidden = true)	允許類的字段在swagger模型定義中隱藏
example	String	“”	字段的示例值	@ApiModelProperty(example= “1”)	該字段的一個(gè)示例值
accessMode	AccessMode	default AccessMode.AUTO	字段的訪問(wèn)模式	@ApiModelProperty(accessMode=READ_ONLY)	允許指定字段的訪問(wèn)模式 (AccessMode.READ_ONLY, READ_WRITE)
reference	String	“”	字段的類型引用		指定對(duì)應(yīng)類型定義的引用，并覆蓋所指定的任何其他的元數(shù)據(jù)
allowEmptyValue	boolean	false	是否允許傳遞的字段為空值	@ApiModelProperty(allowEmptyValue=true)	允許傳遞空值
extensions	Extension[]	@Extension(properties = @ExtensionProperty(name = “”, value = “”))	該注解的擴(kuò)展屬性數(shù)組，可用于第三方	@ApiModelProperty(@Extension(properties = @ExtensionProperty(name = “size”, value = “1”))	返回可選的擴(kuò)展屬性數(shù)組