swagger常用註解說明

2021-08-20 13:56:05 字數 4546 閱讀 1681

常用到的註解有:

1. api標記

api 用在類上,說明該類的作用。可以標記乙個controller類做為swagger 文件資源,使用方式:

@api(value = "/user", description = "operations about user")
與controller註解並列使用。 屬性配置:

屬性名稱

備註value

url的路徑值

br#description

對api資源的描述

basepath

基本路徑可以不配置

position

如果配置多個api 想改變顯示的順序位置

高階特性認證時配置

hidden

配置為true 將在文件中隱藏

在springmvc中的配置如下:

@controller

@api(value = "/pet", description = "operations about pets")

public

class

petcontroller

2. apioperation標記

apioperation:用在方法上,說明方法的作用,每乙個url資源的定義,使用方式:

@apioperation(

value = "find purchase order by id",

notes = "for valid response try integer ids with value <= 5 or > 10. other values will generated exceptions",

response = order,

tags = )

與controller中的方法並列使用。

屬性配置:

屬性名稱

備註value

url的路徑值

br#description

對api資源的描述

basepath

基本路徑可以不配置

position

如果配置多個api 想改變顯示的順序位置

高階特性認證時配置

hidden

配置為true 將在文件中隱藏

response

返回的物件

responsecontainer

這些物件是有效的 "list", "set" or "map".,其他無效

http的狀態碼 預設 200

extensions

擴充套件屬性

在springmvc中的配置如下:

@apioperation(

value = "find purchase order by id",

notes = "for valid response try integer ids with value <= 5 or > 10. other values will generated exceptions",

response = order.class,

tags = )

public responseentitygetorderbyid

(@pathvariable("orderid") string orderid)

throws notfoundexception else

}3. apiparam標記

apiparam請求屬性,使用方式:

public responseentitycreateuser(@requestbody @apiparam(value = "created user object", required = true)  user user)
與controller中的方法並列使用。

屬性配置:

屬性名稱

備註name

屬性名稱

value

屬性值defaultvalue

預設屬性值

allowablevalues

可以不配置

required

是否屬性必填

access

不過多描述

allowmultiple

預設為false

hidden

隱藏該屬性

example

舉例子 在springmvc中的配置如下:

public responseentitygetorderbyid(

@apiparam(value = "id of pet that needs to be fetched", allowablevalues = "range[1,5]", required = true)

@pathvariable("orderid") string orderid)

4. apiresponse

apiresponse:響應配置,使用方式:

@apiresponse(code = 400, message = "invalid user supplied")
與controller中的方法並列使用。 屬性配置:

屬性名稱

備註code

http的狀態碼

message

描述response

預設響應類 void

reference

參考apioperation中配置

responseheaders

參考 responseheader 屬性配置說明

responsecontainer

參考apioperation中配置

在springmvc中的配置如下:

@apioperation(value = "place an order for a pet", response = order.class)

@apiresponses()

public responseentityplaceorder

( @apiparam(value = "order placed for purchasing the pet", required = true) order order)

5. apiresponses

apiresponses:響應集配置,使用方式:

@apiresponses()
與controller中的方法並列使用。 屬性配置:

屬性名稱

備註value

多個apiresponse配置

在springmvc中的配置如下:

@apioperation(value = "place an order for a pet", response = order.class)

@apiresponses()

public responseentityplaceorder

( @apiparam(value = "order placed for purchasing the pet", required = true) order order)

6. responseheader

響應頭設定,使用方法

@responseheader(name="head1",description="response head conf")
與controller中的方法並列使用。 屬性配置:

屬性名稱

備註name

響應頭名稱

description

頭描述response

預設響應類 void

responsecontainer

參考apioperation中配置

在springmvc中的配置如下:

@apimodel(description = "群組")
7. 其他

@apiresponses:用於表示一組響應;

@apiresponse:用在@apiresponses中,一般用於表達乙個錯誤的響應資訊;

@apimodel:描述乙個model的資訊(這種一般用在post建立的時候,使用@requestbody這樣的場景,請求引數無法使用@apiimplicitparam註解進行描述的時候;

@apimodelproperty:描述乙個model的屬性。

swagger註解說明 swagger常用註解說明

常用到的註解有 apiapimodel apimodelproperty apioperation apiparam apiresponse apiresponses responseheader 1.api標記 api 用在類上,說明該類的作用。可以標記乙個controller類做為swagger...

swagger常用註解說明

作者 xiangdong she 作者連線 常用到的註解有 api標記 api 標記可以標記乙個controller類做為swagger 文件資源,使用方式 api value user description operations about user 與controller註解並列使用。屬性配置...

swagger常用註解說明

常用到的註解有 1.api標記 api 用在類上,說明該類的作用。可以標記乙個controller類做為swagger 文件資源,使用方式 api value user description operations about user 與controller註解並列使用。屬性配置 屬性名稱 備註v...