西安電腦網(wǎng)站建設(shè)aso推廣平臺
常用Swagger注解匯總
前言
??在實際編寫后端代碼的過程中,我們可能經(jīng)常使用到 swagger 注解,但是會用不代表了解,你知道每個注解都有什么屬性嗎?你都用過這些屬性嗎?了解它們的作用嗎?本文在此帶大家總結(jié)一下常用的swagger注解,供大家學(xué)習(xí)理解。
文章目錄
- 常用Swagger注解匯總
- 控制器層
- @Api
- @ApiOperation
- @ApiImplicitParam
- @ApiImplicitParams
- @ApiParam
- 實體層
- @ApiModel
- @ApiModelProperty
控制器層
?
@Api
介紹
??此注解應(yīng)用于類、接口或者枚舉上,啟動應(yīng)用時被標(biāo)注的類會掃描到 swagger 源中。默認(rèn)情況下,swagger 核心僅掃描帶有 @Api
注解的類而無視其他的源數(shù)據(jù) (例如:JAX-RS 端口、Serlvet 等等)
??不能標(biāo)注在方法上且一般不單獨使用,常見的做法是搭配 @ApiOperation
注解,作為業(yè)務(wù)接口類的說明。
?
源碼
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個,共有 7 個屬性,不過這里面只有下面這1個屬性比較常用:
1、tags (接口業(yè)務(wù)所屬分組)
這是一個用于控制 API 文檔標(biāo)簽的列表,標(biāo)簽可按資源或者其他標(biāo)識符對操作進行分組。該屬性就是對實現(xiàn)相同業(yè)務(wù)功能的接口類做一個大致的分組,該分組中包括相同業(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 {/*** 測試方法*/@ApiOperation("測試方法")@GetMapping("/test")public R<Void> testApi(){System.out.println("Hello,world");return ok();}
}
說完了常用的屬性,我們再來補充一下剩下的一些不常用屬性:
屬性 | 數(shù)據(jù)類型 | 默認(rèn)值 | 作用 | 示例 | 說明 |
---|---|---|---|---|---|
value | String | “” | 接口分組說明,在實際開發(fā)中并不常用,且值會被 tags 屬性覆蓋 | @Api(value = “操作名稱”) 或 @Api(“操作名稱”) | 隱式地設(shè)置操作標(biāo)簽 (即操作名稱),舊版本支持 (閱讀描述)。 在 Swagger 核心 1.3.X 的版本中,此屬性僅作為主機 API 資源的聲明路徑,到 1.5.X 版本之后就不再關(guān)聯(lián)了。 |
hidden | boolean | false | 隱藏該分組下的所有接口。此外要注意的是,接口的顯示隱藏應(yīng)該根據(jù)特定的安全策略和特定客戶需求來確定 | @Api(hidden = true) | 隱藏資源下的操作。此屬性的值默認(rèn)為 false,當(dāng)設(shè)置為 true 時,該分組的所有操作都會在 swagger 文檔中被隱藏,適用于接口暫時不需要使用時的情況。 |
produces | String | “” | 指定的content-type 的輸出 | @Api(produces=“application/json”) | ??此屬性在新版本的 swagger 中已不再使用,僅用于向下兼容舊版本。對應(yīng)此資源下操作生成的字段。 獲取逗號分割的內(nèi)容類型值,例如,“application/json”,“application/xml” 將會提醒操作生成 JSON 或 XML 輸出。 對于 JAX-RS 資源,如果存在將會自動獲取 @Produces 注解的值,同時也可用于覆蓋 Swapper 文檔的 @Produces 的值。 |
consumes | String | “” | 指定的content-type 的輸入 | @Api(consumes=“application/xml”) | 對應(yīng)此資源下操作消費的字段。 獲取逗號分割的內(nèi)容類型值。例如例如,“application/json”,“application/xml” 將會提醒操作接收 JSON 或 XML 輸入。 對于 JAX-RS 資源,如果存在將會自動獲取 @Consumes 注解的值,同時也可用于覆蓋 Swagger 文檔的 @Consumes 的值。 |
protocols | String | “” | 網(wǎng)絡(luò)請求協(xié)議 | @Api(protocols = “http,https”) | 設(shè)置此資源下操作的指定協(xié)議(或方案)。 以逗號分割可用的協(xié)議值,可用值:http, https, ws, wss |
authorizations | Authorization[] | @Authorization(value = “”) | 規(guī)定接口分組的授權(quán)方案 | 對應(yīng)操作對象的安全字段。 獲取此資源下操作的授權(quán) (安全需求) 列表,這可能會被特定的操作覆蓋。 |
?
@ApiOperation
介紹
??@ApiOperation
注解可應(yīng)用于方法或類上,通常標(biāo)注在方法上作為業(yè)務(wù)接口的名稱,描述其操作或者描述針對于特定路徑的 HTTP 方法。默認(rèn)情況下,具有相同效果的操作被分組在一個單獨的操作對象中,而 HTTP 方法和路徑的組合將會創(chuàng)建一個獨一無二的操作。此外,此注解提供了豐富的屬性來允許我們自定義接口的描述信息,包括接口名稱和所屬分組等。
?
源碼
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個,共有 17 個屬性。不過這里面只有以下 2 個屬性比較常用:
?
1、value (接口名稱)
對應(yīng)操作的摘要字段。此屬性提供接口的簡要描述(即接口說明),最多 120 個字符或者少于 Swagger-UI
頁面可展示的。
/*** 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 (接口描述)
對應(yīng)操作的詳情字段。這是一段冗長的操作描述,沒有字?jǐn)?shù)限制,通常適用于當(dāng) value
屬性無法解釋清楚時對接口操作的補充說明。
/*** 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);}
}
說完了常用的屬性,我們再來補充一下剩下的一些不常用屬性:
屬性 | 數(shù)據(jù)類型 | 默認(rèn)值 | 作用 | 示例 | 說明 |
---|---|---|---|---|---|
tags | String[] | “” | 定義接口分組,如果一個接口涉及到多個業(yè)務(wù)場景,那這個時候需要我們對接口進行多個分組 | @ApiOperation(tags={“測試標(biāo)簽1”, “測試標(biāo)簽2”}) | 一個用于控制 API 文檔標(biāo)簽的列表,標(biāo)簽可按資源或者其他標(biāo)識符對操作進行分組。此外,操作的 Api 注解的 value 或者 tags 屬性將會覆蓋其單個的非空值。 |
response | Class<?> | Void.class | 指定響應(yīng)的數(shù)據(jù)類型 | @ApiOperation(response = ReturnResult.class) | 操作返回的響應(yīng)類型 在 JAX-RS 應(yīng)用程序中,方法的返回類型將會自動使用,除了 javax.ws.core.Response 。而在其他情況下,操作返回類型默認(rèn)為 void ,因為不知道實際的響應(yīng)類型。設(shè)置此屬性將會覆蓋任何自動派生的數(shù)據(jù)類型 如果被用到的值是用一個類 (Integer、Long) 的基本數(shù)據(jù)類型表示的,那么則會使用相應(yīng)的基本數(shù)據(jù)類型響應(yīng) |
responseContainer | String | “” | 包裝HTTP響應(yīng)的容器類型 | @ApiOperation(responseContainer= “List”) | 聲明一個包裝響應(yīng)的容器,有效值只有 “List”、“Set”、“Map”,其他值都會被忽略。 |
responseReference | String | “” | 支持遠程調(diào)用的響應(yīng)數(shù)據(jù)類型,比 response 屬性優(yōu)先級更高 | @ApiOperation(responseReference= “java.lang.Integer”) | 指定一個響應(yīng)類型的引用。此引用可以是本地的或者遠程的并且將按原樣使用,覆任何的指定的 response 屬性類 |
httpMethod | String | “” | 接口使用的HTTP方法 | @ApiOperation(httpMethod= “GET”) | 對應(yīng)使用的HTTP方法 如果是無狀態(tài)的,在 JAX-RS 應(yīng)用程序中,下列 JAX-RS 注解將會被掃描且使用:@GET、@HEAD、@POST、@PUT、@DELETE 和 @OPTIONS。注意即使它不是 JAX-RS規(guī)范指定的部分(也可以被掃描并使用),如果您創(chuàng)建并使用 @PATCH 注解,它也會被解析并使用,如果設(shè)置了此屬性,那么將會覆蓋 JAX-RS 注解。 對于 Sevlet 而言,您必須手動指定 HTTP 方法,可接收的值是 “GET”、“HEAD”、“POST”、“PUT”、“DELETE”、“GET”、“DELETE” 和 “PATCH”。 |
nickname | String | “” | 接口別名,方便前后端溝通使用,沒有其他含義 | @ApiOperation(nickname= “測試別名”) | 對應(yīng)操作 ID 字段。 此操作 ID 被用于第三方工具唯一識別此操作的手段,在 Swagger 2.0 中,這不是必填參數(shù),如果不提供值可以為空。 |
produces | String | “” | 指定的content-type 的輸出 | @ApiOperation(produces=“application/json”) | 對應(yīng)此資源下操作生成的字段。 獲取逗號分割的內(nèi)容類型值,例如,“application/json”,“application/xml” 將會提醒操作生成 JSON 或 XML 輸出。 對于 JAX-RS 資源,如果存在將會自動獲取 @Produces 注解的值,同時也可用于覆蓋 Swapper 文檔的 @Produces 的值。 |
consumes | String | “” | 指定的content-type 的輸入 | @ApiOperation(consumes=“application/xml”) | 對應(yīng)此資源下操作消費的字段。 獲取逗號分割的內(nèi)容類型值。例如例如,“application/json”,“application/xml” 將會提醒操作接收 JSON 或 XML 輸入。 對于 JAX-RS 資源,如果存在將會自動獲取 @Consumes 注解的值,同時也可用于覆蓋 Swagger 文檔的 @Consumes 的值。 |
protocols | String | “” | 網(wǎng)絡(luò)請求協(xié)議 | @ApiOperation(protocols = “http,https”) | 設(shè)置此資源下操作的指定協(xié)議(或方案)。 以逗號分割可用的協(xié)議值,可用值:http, https, ws, wss |
authorizations | Authorization[] | @Authorization(value = “”) | 定義接口的授權(quán)方案 | 對應(yīng)操作對象的安全字段。 獲取此資源下操作的授權(quán) (安全需求) 列表,這可能會被特定的操作覆蓋。 | |
hidden | boolean | false | 此屬性用于隱藏接口,但要注意的是,接口的顯示隱藏應(yīng)該根據(jù)特定的安全策略和特定客戶需求來 | @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自動生成,一般不用設(shè)置 | @ApiOperation(code = 404) | HTTP 響應(yīng)狀態(tài)碼,其值應(yīng)該是正式 HTTP 狀態(tài)碼定義的其中之一 |
extensions | Extension[] | @Extension(properties = @ExtensionProperty(name = “”, value = “”)) | 可選的擴展屬性數(shù)組 | @ApiOperation(extensions = @Extension(properties = @ExtensionProperty(name = “key”, value = “value”))) | 可選的擴展屬性數(shù)組 |
ignoreJsonView | boolean | false | 忽略JsonView 注解 | @ApiOperation(ignoreJsonView = true) | 當(dāng)解析操作和類型時忽略 @JsonView 注解,用于向后兼容 |
?
@ApiImplicitParam
前言
??此注解只能標(biāo)注在方法上,代表了方法中的一個獨立的參數(shù),如果方法有多個參數(shù),可以和 @ApiImplicitParams
注解搭配使用。
??當(dāng) ApiParam
注解綁定了一個 JAX-RS 的參數(shù)、方法、或者字段時,它允許您以微調(diào)的方式手動定義一個參數(shù)。這是當(dāng)使用 Servlet 或者其他非 JAX-RS 環(huán)境時定義參數(shù)的唯一方法。
??此注解和 @ApiParam
注解一樣都可以應(yīng)用于方法參數(shù)上,不過 @ApiParam
更適用于參數(shù)不是包裝類或者 String
的情況,此時配合 @ApiModel
和@ApiModelProperty
再好不過,而 @ApiImplicitParam 通常適用于方法中有單個或多個參數(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 個屬性。不過這里面只有以下 2 個屬性比較常用:
1、name (參數(shù)名稱)
此屬性表示參數(shù)的名稱。為了保持適當(dāng)?shù)?Swagger 功能,當(dāng)根據(jù) parameType() (指參數(shù)類型) 命名參數(shù)時,請遵循以下規(guī)則:
(1)、如果參數(shù)類型是路徑,其名稱應(yīng)當(dāng)是路徑中所關(guān)聯(lián)的那部分 (相對路徑)
(2)、對于所有的其他情況,其名稱應(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ù)說明)
這是一個簡短的參數(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請求")@GetMapping("/show")public R<String> show(HttpServletRequest request) {String method = request.getMethod();return R.ok(method);}
}
3、allowableValues (參數(shù)范圍)
限制此參數(shù)接收的值,以下有三種方法可以描述請求參數(shù)的范圍:
(1)、設(shè)置一個值的列表,提供一個以逗號分割的列表。例如:first, second, third。
(2)、設(shè)置一個值的范圍,以 “range” 開始這個值,周圍用方括號表示最小值和最大值,或使用圓括號表示獨占的最小值和最大值。例如:range[1, 5]、range(1, 5), range[1, 5)。注意,此屬性需要配合 dataTypeClass
屬性才有用,單獨設(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 {/*** 獲取隨機數(shù)* @param seed 隨機數(shù)種子*/@ApiOperation("獲取隨機數(shù)")@ApiImplicitParam(name = "seed", value = "隨機數(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();}
}
說完了常用的屬性,我們再來補充一下剩下的一些不常用屬性:
屬性 | 數(shù)據(jù)類型 | 默認(rèn)值 | 概述 | 示例 | 說明 |
---|---|---|---|---|---|
defaultValue | String | “” | 參數(shù)默認(rèn)值 | @ApiImplicitParam(defaultValue = “1”) | 描述參數(shù)的默認(rèn)值,當(dāng)請求參數(shù)中有分頁參數(shù)或有需要設(shè)置默認(rèn)值的參數(shù),可設(shè)置此屬性 |
access | String | “” | 允許API文檔過濾參數(shù),更多細(xì)節(jié)請查看 SwaggerSpecFilter 類 | ||
allowMultiple | String | “” | 此參數(shù)是否能接受多個值 | @ApiImplicitParam(allowMultiple= true) | 指定此參數(shù)是否能在各種情況下能夠接收多個值,默認(rèn)值為false |
dataType | String | “” | 數(shù)據(jù)類型 | @ApiImplicitParam(dataType=“int”) | 參數(shù)的數(shù)據(jù)類型,可以是類名或者基本數(shù)據(jù)類型 |
dataTypeClass | Class<?> | Void.class | class 類型,此屬性不定義的話程序可能會有警告 | @ApiImplicitParam(dataTypeClass = String.class) | 參數(shù)的 class 類型,如果此屬性指定了值的話會覆蓋 dataType 提供的 |
paramType | String | “” | 參數(shù)的HTTP參數(shù)類型 | @ApiImplicitParam(param=“query”) | 參數(shù)的參數(shù)類型,有效值是 path、query、body、header 或者 form,其他值會被忽略 |
example | String | “” | 參數(shù)示例 | @ApiImplicitParam(example=“1”) | 一個非 body 類型的單獨參數(shù)示例 |
examples | Example | @Example(value = @ExampleProperty(mediaType = “”, value = “”)) | 參數(shù)示例集合 | 參數(shù)示例,僅適用于body參數(shù) | |
type | String | “” | 參數(shù)類型 | @ApiImplicitParam(type = “int”) | 添加了覆蓋所檢測到的類型的能力 |
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 注解的包裝器,單獨使用沒有意義,必須和 @ApiImplicitParam 進行搭配,當(dāng)接口方法中有一個及以上的參數(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
注解有且只有一個常用的屬性:
1、value(注解列表)
一個用于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ù)位置的注解,其主要作用是用來給接口中的參數(shù)定義相關(guān)的參數(shù)說明,旨在幫助相關(guān)技術(shù)人員理解接口中每個參數(shù)的含義。注意,此注解只能在 JAX-RS 1.x/2.x
注解的組合中使用,和 @ApiImplicitParam
注解同樣的是,都可以標(biāo)注在方法上,對方法的參數(shù)進行解釋說明。唯一的不同點是,@ApiImplicitParam
注解比 @ApiParam
更適合標(biāo)注在包裝類或 Spring 類上,且配合 @ApiImplicitParams
可以做到支持多個參數(shù),而 @ApiParam
只能有一個。
?
源碼
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 個屬性。不過這里面只有以下 2 個屬性比較常用:
1、name(參數(shù)名稱)
此屬性代表了參數(shù)的名稱,值可能來自字段、方法或參數(shù)名稱,應(yīng)當(dā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("打印消息")@ApiParam(name = "msg")@GetMapping("/printMsg")public R<Void> printMsg(String msg) {System.out.println("msg = " + msg);return ok();}
}
2、value(參數(shù)說明)
這是一段簡短的參數(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 (是否必填)
指定請求參數(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);}}
說完了常用的屬性,我們再來補充一下剩下的一些不常用屬性:
屬性 | 數(shù)據(jù)類型 | 默認(rèn)值 | 概述 | 示例 | 說明 |
---|---|---|---|---|---|
defaultValue | String | “” | 參數(shù)的默認(rèn)值 | @ApiParam(defaultValue = “1”) | 描述參數(shù)的默認(rèn)值,當(dāng)請求參數(shù)中有分頁參數(shù)或有需要設(shè)置默認(rèn)值的參數(shù),可設(shè)置此屬性 |
access | String | “” | 允許API文檔過濾參數(shù),更多細(xì)節(jié)請查看 SwaggerSpecFilter 類 | ||
allowMultiple | boolean | false | 此參數(shù)是否能接受多個值 | @ApiParam(allowMultiple= true) | 指定此參數(shù)是否能在各種情況下能夠接收多個值,默認(rèn)值為false |
hidden | boolean | false | 控制參數(shù)的隱藏或顯示 | @ApiParam(hidden = true) | 隱藏參數(shù)列表中的此參數(shù) |
example | String | “” | 參數(shù)示例 | @ApiParam(example=“1”) | 一個非 body 類型的單獨參數(shù)示例 |
examples | Example | @Example(value = @ExampleProperty(mediaType = “”, value = “”)) | 參數(shù)示例集合 | 參數(shù)示例,僅適用于body參數(shù) | |
type | String | “” | 參數(shù)類型 | @ApiParam(type = “int”) | 添加了覆蓋所檢測到的類型的能力 |
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)于請求參數(shù)的注解,通常swagger注解也會配合這些注解一起使用,了解這些注解對你百利而無一害。
注解 說明 @RequestParam Spring的請求參數(shù)注解,可以標(biāo)注在方法參數(shù)上,如果前后端參數(shù)不對應(yīng)的話,可以使用此注解進行參數(shù)綁定 @RequestBody 將當(dāng)前參數(shù)綁定為請求主體,POST、PUT方法中常用 @RequestHeader 如果方法需要接受請求頭參數(shù),那么可以使用此注解,表示當(dāng)前參數(shù)是一個請求頭參數(shù) @RequestAttribute 將當(dāng)前參數(shù)綁定為HTTP請求中的一個屬性,通過 request.getAttribute() 方法可獲取屬性值 @RequestPart 可以將 “multipart/form-data” 請求的參數(shù)和方法參數(shù)進行相關(guān)聯(lián)
?
實體層
@ApiModel
介紹
??為模型或視圖對象提供額外的 swagger 說明信息, 被標(biāo)注的類將會 “ 自我介紹 ”,因為它們在操作中被用作類型,不過程序員們更喜歡著眼于類的內(nèi)部結(jié)構(gòu)。此注解是作用在接口相關(guān)的實體類上的注解,用來對該接口的相關(guān)實體類添加額外的描述信息,一般和 @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 個屬性,不過這里面只有下面這1個屬性比較常用:
1、value (模型描述)
為模型提供一個替代名稱(替代類名),如果沒有標(biāo)注此屬性,默認(rèn)情況下使用類名。
實體層
/*** 用戶對象** @author 莪是男神*/
@Data
@ApiModel("用戶信息")
public class UserInfo implements Serializable {private static final long serialVersionUID = 1L;/** 用戶ID */private Long userId;/** 部門ID */private Long deptId;/** 用戶賬號 */private String userName;/** 用戶昵稱 */private String nickName;/** 用戶郵箱 */private String email;/** 手機號碼 */private String phonenumber;/** 用戶性別 */private String sex;/** 用戶頭像 */private String avatar;/** 密碼 */private String password;/** 帳號狀態(tài)(0正常 1停用) */private String status;/** 刪除標(biāo)志(0代表存在 2代表刪除) */private String delFlag;/** 最后登錄IP */private String loginIp;/** 最后登錄時間 */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);}}
說完了常用的屬性,我們再來補充一下剩下的一些不常用屬性:
屬性 | 數(shù)據(jù)類型 | 默認(rèn)值 | 概述 | 示例 | 說明 |
---|---|---|---|---|---|
description | String | “” | 類描述。 在實際開發(fā)中,此屬性一般會配合 value 屬性進行使用,很少會出現(xiàn)只是用 value 屬性而不使用 description 屬性的情況。 | @ApiMode(description = “系統(tǒng)用戶的詳細(xì)信息”) | 為此模型提供一個冗長的描述 |
parent | Class<?> | Void.class | 描述類的繼承關(guān)系 | @ApiModel(parent = Object.class) | 為模型提供一個父類,允許描述其中的繼承關(guān)系 |
discriminator | String | “” | 實現(xiàn)類的多態(tài)性 | @ApiModel(discriminator= “userId”) | 此屬性用于支持模型繼承以及多態(tài)性。 其值用作鑒別器的字段名稱,基于這個字段,可以斷言需要使用哪種子類型 |
subTypes | Class<?>[] | {} | 展示繼承接口相關(guān)實體類class的子類 | @ApiModel(subTypes={String.class}) | 一個繼承此模型的子類數(shù)組 |
reference | String | “” | 實體類的類型引用 | 指定對應(yīng)類型定義的引用,并覆蓋所指定的任何其他的元數(shù)據(jù) |
?
@ApiModelProperty
介紹
??此注解可標(biāo)注在方法或字段上,通常配合 @ApiModel 注解一起使用,用于添加或操作接口相關(guān)實體類的字段信息
?
源碼
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個,共有 14 個屬性和一個枚舉,不過這里面只有下面這1個屬性比較常用:
1、value (字段描述)
一段簡短的字段描述。
/*** 用戶對象** @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;/** 用戶賬號 */@ApiModelProperty("用戶賬號")private String userName;/** 用戶昵稱 */@ApiModelProperty("用戶昵稱")private String nickName;/** 用戶郵箱 */@ApiModelProperty("用戶郵箱")private String email;/** 手機號碼 */@ApiModelProperty("手機號碼")private String phonenumber;/** 用戶性別 */@ApiModelProperty("用戶性別")private String sex;/** 用戶頭像 */@ApiModelProperty("用戶頭像")private String avatar;/** 密碼 */@ApiModelProperty("密碼")private String password;/** 帳號狀態(tài)(0正常 1停用) */@ApiModelProperty("帳號狀態(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;/** 最后登錄時間 */@ApiModelProperty("最后登錄時間")private Date loginDate;}
說完了常用的屬性,我們再來補充一下剩下的一些不常用屬性:
屬性 | 數(shù)據(jù)類型 | 默認(rèn)值 | 概述 | 示例 | 說明 |
---|---|---|---|---|---|
name | String | “” | 字段的名稱 | @ApiModelProperty(name = “userId”) | 允許覆蓋屬性的名稱 |
defaultValue | String | “” | 字段的默認(rèn)值 | @ApiModelProperty(defaultValue = “1”) | 描述屬性的默認(rèn)值,當(dāng)屬性需要設(shè)置默認(rèn)值時,可設(shè)置此屬性 |
access | String | “” | 允許API文檔過濾參數(shù),更多細(xì)節(jié)請查看 SwaggerSpecFilter 類 | ||
notes | String | “” | 暫時沒用 | @ApiModelProperty(notes= “暫時沒用”) | 注解的擴展屬性,當(dāng)前未使用。 |
dataType | String | “” | 描述字段的數(shù)據(jù)類型 | @ApiModelProperty(dataType=“int”) | 這個屬性描述字段的數(shù)據(jù)類型,其值可以是對象或者是基本數(shù)據(jù)類型,而且會覆蓋從類屬性中讀取的數(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”) | 該字段的一個示例值 |
accessMode | AccessMode | default AccessMode.AUTO | 字段的訪問模式 | @ApiModelProperty(accessMode=READ_ONLY) | 允許指定字段的訪問模式 (AccessMode.READ_ONLY, READ_WRITE) |
reference | String | “” | 字段的類型引用 | 指定對應(yīng)類型定義的引用,并覆蓋所指定的任何其他的元數(shù)據(jù) | |
allowEmptyValue | boolean | false | 是否允許傳遞的字段為空值 | @ApiModelProperty(allowEmptyValue=true) | 允許傳遞空值 |
extensions | Extension[] | @Extension(properties = @ExtensionProperty(name = “”, value = “”)) | 該注解的擴展屬性數(shù)組,可用于第三方 | @ApiModelProperty(@Extension(properties = @ExtensionProperty(name = “size”, value = “1”)) | 返回可選的擴展屬性數(shù)組 |