国产亚洲精品福利在线无卡一,国产精久久一区二区三区,亚洲精品无码国模,精品久久久久久无码专区不卡

當(dāng)前位置: 首頁 > news >正文

西安電腦網(wǎng)站建設(shè)aso推廣平臺

西安電腦網(wǎng)站建設(shè),aso推廣平臺,東莞網(wǎng)站建設(shè)多少錢,網(wǎng)站自動適應(yīng)屏幕常用Swagger注解匯總 前言 在實際編寫后端代碼的過程中,我們可能經(jīng)常使用到 swagger 注解,但是會用不代表了解,你知道每個注解都有什么屬性嗎?你都用過這些屬性嗎?了解它們的作用嗎?本文在此帶大家總結(jié)一下…

常用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();}
}

@Api注解的tags屬性

說完了常用的屬性,我們再來補充一下剩下的一些不常用屬性:

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

@ApiOperation注解的value屬性

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

@ApiOperation注解的notes屬性

說完了常用的屬性,我們再來補充一下剩下的一些不常用屬性:

屬性數(shù)據(jù)類型默認(rèn)值作用示例說明
tagsString[]“”定義接口分組,如果一個接口涉及到多個業(yè)務(wù)場景,那這個時候需要我們對接口進行多個分組@ApiOperation(tags={“測試標(biāo)簽1”, “測試標(biāo)簽2”})一個用于控制 API 文檔標(biāo)簽的列表,標(biāo)簽可按資源或者其他標(biāo)識符對操作進行分組。此外,操作的 Api 注解的 value 或者 tags 屬性將會覆蓋其單個的非空值。
responseClass<?>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)
responseContainerString“”包裝HTTP響應(yīng)的容器類型@ApiOperation(responseContainer= “List”)聲明一個包裝響應(yīng)的容器,有效值只有 “List”、“Set”、“Map”,其他值都會被忽略。
responseReferenceString“”支持遠程調(diào)用的響應(yīng)數(shù)據(jù)類型,比 response 屬性優(yōu)先級更高@ApiOperation(responseReference= “java.lang.Integer”)指定一個響應(yīng)類型的引用。此引用可以是本地的或者遠程的并且將按原樣使用,覆任何的指定的 response 屬性類
httpMethodString“”接口使用的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”。
nicknameString“”接口別名,方便前后端溝通使用,沒有其他含義@ApiOperation(nickname= “測試別名”)對應(yīng)操作 ID 字段。
此操作 ID 被用于第三方工具唯一識別此操作的手段,在 Swagger 2.0 中,這不是必填參數(shù),如果不提供值可以為空。
producesString“”指定的content-type 的輸出@ApiOperation(produces=“application/json”)對應(yīng)此資源下操作生成的字段。
獲取逗號分割的內(nèi)容類型值,例如,“application/json”,“application/xml” 將會提醒操作生成 JSON 或 XML 輸出。
對于 JAX-RS 資源,如果存在將會自動獲取 @Produces 注解的值,同時也可用于覆蓋 Swapper 文檔的 @Produces 的值。
consumesString“”指定的content-type 的輸入@ApiOperation(consumes=“application/xml”)對應(yīng)此資源下操作消費的字段。
獲取逗號分割的內(nèi)容類型值。例如例如,“application/json”,“application/xml” 將會提醒操作接收 JSON 或 XML 輸入。
對于 JAX-RS 資源,如果存在將會自動獲取 @Consumes 注解的值,同時也可用于覆蓋 Swagger 文檔的 @Consumes 的值。
protocolsString“”網(wǎng)絡(luò)請求協(xié)議@ApiOperation(protocols = “http,https”)設(shè)置此資源下操作的指定協(xié)議(或方案)。
以逗號分割可用的協(xié)議值,可用值:http, https, ws, wss
authorizationsAuthorization[]@Authorization(value = “”)定義接口的授權(quán)方案對應(yīng)操作對象的安全字段。
獲取此資源下操作的授權(quán) (安全需求) 列表,這可能會被特定的操作覆蓋。
hiddenbooleanfalse此屬性用于隱藏接口,但要注意的是,接口的顯示隱藏應(yīng)該根據(jù)特定的安全策略和特定客戶需求來@ApiOperation(hidden= true)操作列表中隱藏此操作
responseHeadersResponseHeader[]@ResponseHeader(name = “”, response = Void.class)HTTP響應(yīng)頭參數(shù)@ApiOperation(responseHeaders = {@ResponseHeader(name = “auth”, response = String.class)})在響應(yīng)中可能提供的響應(yīng)頭列表
codeint200HTTP狀態(tài)碼,swagger自動生成,一般不用設(shè)置@ApiOperation(code = 404)HTTP 響應(yīng)狀態(tài)碼,其值應(yīng)該是正式 HTTP 狀態(tài)碼定義的其中之一
extensionsExtension[]@Extension(properties = @ExtensionProperty(name = “”, value = “”))可選的擴展屬性數(shù)組@ApiOperation(extensions = @Extension(properties = @ExtensionProperty(name = “key”, value = “value”)))可選的擴展屬性數(shù)組
ignoreJsonViewbooleanfalse忽略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);}
}

@ApiImplicitParam注解的name屬性

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

@ApiImplicitParam注解的value屬性

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

@ApiImplicitParam注解的allowableValues屬性01

當(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();}
}

@ApiImplicitParam注解的required屬性

說完了常用的屬性,我們再來補充一下剩下的一些不常用屬性:

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

@ApiImplicitParams注解的value屬性

@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();}
}

@ApiParam注解的name屬性

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)值概述示例說明
defaultValueString“”參數(shù)的默認(rèn)值@ApiParam(defaultValue = “1”)描述參數(shù)的默認(rèn)值,當(dāng)請求參數(shù)中有分頁參數(shù)或有需要設(shè)置默認(rèn)值的參數(shù),可設(shè)置此屬性
accessString“”允許API文檔過濾參數(shù),更多細(xì)節(jié)請查看 SwaggerSpecFilter 類
allowMultiplebooleanfalse此參數(shù)是否能接受多個值@ApiParam(allowMultiple= true)指定此參數(shù)是否能在各種情況下能夠接收多個值,默認(rèn)值為false
hiddenbooleanfalse控制參數(shù)的隱藏或顯示@ApiParam(hidden = true)隱藏參數(shù)列表中的此參數(shù)
exampleString“”參數(shù)示例@ApiParam(example=“1”)一個非 body 類型的單獨參數(shù)示例
examplesExample@Example(value = @ExampleProperty(mediaType = “”, value = “”))參數(shù)示例集合參數(shù)示例,僅適用于body參數(shù)
typeString“”參數(shù)類型@ApiParam(type = “int”)添加了覆蓋所檢測到的類型的能力
formatString“”參數(shù)格式@ApiParam(type = “integer”, format=“int64”)添加了提供自定義格式的能力
allowEmptyValuebooleanfalse是否允許傳遞空值@ApiParam(allowEmptyValue=true)添加了設(shè)置空值格式的能力
readOnlybooleanfalse是否只讀@ApiParam(readOnly=true)添加了被認(rèn)定為只讀的能力
collectionFormatString“”集合的格式添加了使用數(shù)組類型覆蓋集合格式的能力

Tips

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

注解說明
@RequestParamSpring的請求參數(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)值概述示例說明
descriptionString“”類描述。
在實際開發(fā)中,此屬性一般會配合 value 屬性進行使用,很少會出現(xiàn)只是用 value 屬性而不使用 description 屬性的情況。
@ApiMode(description = “系統(tǒng)用戶的詳細(xì)信息”)為此模型提供一個冗長的描述
parentClass<?>Void.class描述類的繼承關(guān)系@ApiModel(parent = Object.class)為模型提供一個父類,允許描述其中的繼承關(guān)系
discriminatorString“”實現(xiàn)類的多態(tài)性@ApiModel(discriminator= “userId”)此屬性用于支持模型繼承以及多態(tài)性。
其值用作鑒別器的字段名稱,基于這個字段,可以斷言需要使用哪種子類型
subTypesClass<?>[]{}展示繼承接口相關(guān)實體類class的子類@ApiModel(subTypes={String.class})一個繼承此模型的子類數(shù)組
referenceString“”實體類的類型引用指定對應(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;}

@ApiModelProperty注解的value屬性

說完了常用的屬性,我們再來補充一下剩下的一些不常用屬性:

屬性數(shù)據(jù)類型默認(rèn)值概述示例說明
nameString“”字段的名稱@ApiModelProperty(name = “userId”)允許覆蓋屬性的名稱
defaultValueString“”字段的默認(rèn)值@ApiModelProperty(defaultValue = “1”)描述屬性的默認(rèn)值,當(dāng)屬性需要設(shè)置默認(rèn)值時,可設(shè)置此屬性
accessString“”允許API文檔過濾參數(shù),更多細(xì)節(jié)請查看 SwaggerSpecFilter 類
notesString“”暫時沒用@ApiModelProperty(notes= “暫時沒用”)注解的擴展屬性,當(dāng)前未使用。
dataTypeString“”描述字段的數(shù)據(jù)類型@ApiModelProperty(dataType=“int”)這個屬性描述字段的數(shù)據(jù)類型,其值可以是對象或者是基本數(shù)據(jù)類型,而且會覆蓋從類屬性中讀取的數(shù)據(jù)類型。
requiredbooleanfalse是否必填@ApiModelProperty(required=true)指定字段為必要的還是非必要的
positionint0指定字段在swagger文檔中的顯示順序@ApiModelProperty(position= 1)允許排序類的字段
hiddenbooleanfalse隱藏類的字段@ApiModelProperty(hidden = true)允許類的字段在swagger模型定義中隱藏
exampleString“”字段的示例值@ApiModelProperty(example= “1”)該字段的一個示例值
accessModeAccessModedefault AccessMode.AUTO字段的訪問模式@ApiModelProperty(accessMode=READ_ONLY)允許指定字段的訪問模式 (AccessMode.READ_ONLY, READ_WRITE)
referenceString“”字段的類型引用指定對應(yīng)類型定義的引用,并覆蓋所指定的任何其他的元數(shù)據(jù)
allowEmptyValuebooleanfalse是否允許傳遞的字段為空值@ApiModelProperty(allowEmptyValue=true)允許傳遞空值
extensionsExtension[]@Extension(properties = @ExtensionProperty(name = “”, value = “”))該注解的擴展屬性數(shù)組,可用于第三方@ApiModelProperty(@Extension(properties = @ExtensionProperty(name = “size”, value = “1”))返回可選的擴展屬性數(shù)組
http://aloenet.com.cn/news/28487.html

相關(guān)文章:

  • 對網(wǎng)站設(shè)計的建議網(wǎng)絡(luò)推廣渠道和方式
  • 懷化做網(wǎng)站的公司怎么做關(guān)鍵詞排名靠前
  • 模擬網(wǎng)站建設(shè)對網(wǎng)絡(luò)營銷的認(rèn)識
  • 網(wǎng)站url改版線下營銷方式主要有哪些
  • 做那種網(wǎng)站賺錢廣州代運營公司有哪些
  • 做視頻網(wǎng)站 視頻放在哪里西安網(wǎng)頁設(shè)計
  • 不準(zhǔn)別人網(wǎng)站做反鏈好網(wǎng)站制作公司
  • 織夢網(wǎng)站如何做地區(qū)分站青島seo整站優(yōu)化招商電話
  • 重慶網(wǎng)站建設(shè)哪個公司好百度關(guān)鍵詞搜索量
  • wordpress模板用法深圳百度網(wǎng)站排名優(yōu)化
  • h5如何做多頁面網(wǎng)站愛站查詢
  • 網(wǎng)頁設(shè)計技能證書怎么考寧波如何做抖音seo搜索優(yōu)化
  • 做網(wǎng)站需要學(xué)那幾個軟件whois查詢 站長工具
  • 蘭溪做網(wǎng)站seo優(yōu)化工作內(nèi)容做什么
  • 品牌宣傳型網(wǎng)站構(gòu)成營銷策劃與運營公司
  • 網(wǎng)站開發(fā)有沒有前途12345微信公眾號
  • 站長統(tǒng)計向日葵app下載百度推廣投訴熱線
  • 東莞網(wǎng)站建設(shè)公司中國企業(yè)500強
  • 購物網(wǎng)站制作流程關(guān)鍵詞查找
  • 打開網(wǎng)頁時網(wǎng)站頂部顯示廣告隨后消失的廣告怎么做seo專員崗位要求
  • 整站優(yōu)化方案網(wǎng)站優(yōu)化技巧
  • 園區(qū)門戶網(wǎng)站建設(shè)方案大型網(wǎng)站seo課程
  • app那個網(wǎng)站開發(fā)比較好內(nèi)部搜索引擎優(yōu)化
  • 網(wǎng)站可以叫做系統(tǒng)嗎企業(yè)培訓(xùn)課程
  • 蘇州公司網(wǎng)站seo外鏈推廣員
  • 空間鏈接制作網(wǎng)站百度推廣中心
  • 軟件測試培訓(xùn)一般多少錢長春seo排名優(yōu)化
  • 方特網(wǎng)站是誰做的seo案例視頻教程
  • 外國做掛的網(wǎng)站是多少錢外貿(mào)營銷型網(wǎng)站建設(shè)公司
  • my77738免費域名查詢seo薪酬水平