swagger常用註解

2021-09-02 21:41:14 字數 2990 閱讀 5405

swagger2常用註解說明

2023年08月01日 14:00:38

說明: 

1.這裡使用的版本:springfox-swagger2(2.4)springfox-swagger-ui (2.4) 

2.這裡是說明常用註解的含義和基本用法(也就是說已經對swagger進行整合完成) 

沒有整合的請參見 

springboot整合springfox-swagger2構建restful api

springmvc整合springfox-swagger2構建restful api

官網wiki

常用註解: 

- @api()用於類; 

表示標識這個類是swagger的資源 

- @apioperation()用於方法; 

表示乙個http請求的操作 

- @apiparam()用於方法,引數,字段說明; 

表示對引數的新增元資料(說明或是否必填等) 

- @apimodel()用於類 

表示對類進行說明,用於引數用實體類接收 

- @apimodelproperty()用於方法,字段 

表示對model屬性的說明或者資料操作更改 

- @apiignore()用於類,方法,方法引數 

表示這個方法或者類被忽略 

- @apiimplicitparam() 用於方法 

表示單獨的請求引數 

- @apiimplicitparams() 用於方法,包含多個 @apiimplicitparam

具體使用舉例說明: 

@api()

用於類;表示標識這個類是swagger的資源 

tags–表示說明 

value–也是說明,可以使用tags替代 

但是tags如果有多個值,會生成多個list

@api(value="使用者controller",tags=)

@restcontroller

public

class usercontroller

效果圖: 

@apioperation() 用於方法;表示乙個http請求的操作 

value用於方法描述 

notes用於提示內容 

tags可以重新分組(視情況而用) 

@apiparam() 用於方法,引數,字段說明;表示對引數的新增元資料(說明或是否必填等) 

name–引數名 

value–引數說明 

required–是否必填

@api(value="使用者controller",tags=)

@restcontroller

public

class usercontroller ,notes="注意問題點")

public user getuserinfo(@apiparam(name="id",value="使用者id",required=true) long id,@apiparam(name="username",value="使用者名稱") string username)

}

效果圖: 

@apimodel()用於類 ;表示對類進行說明,用於引數用實體類接收 

value–表示物件名 

description–描述 

都可省略 

@apimodelproperty()用於方法,字段; 表示對model屬性的說明或者資料操作更改 

value–字段說明 

name–重寫屬性名字 

datatype–重寫屬性型別 

required–是否必填 

example–舉例說明 

hidden–隱藏

@apimodel(value="user物件",description="使用者物件user")

public

class

user

implements

serializable

@apioperation("更改使用者資訊")

public

intupdateuserinfo(@requestbody @apiparam(name="使用者物件",value="傳入json格式",required=true) user user)

效果圖: 

@apiignore()用於類或者方法上,可以不被swagger顯示在頁面上 

比較簡單, 這裡不做舉例

@apiimplicitparam() 用於方法 

表示單獨的請求引數 

@apiimplicitparams() 用於方法,包含多個 @apiimplicitparam 

name–引數ming 

value–引數說明 

datatype–資料型別 

paramtype–引數型別 

example–舉例說明

@apioperation("查詢測試")

//@apiimplicitparam(name="name",value="使用者名稱",datatype="string", paramtype = "query")

@apiimplicitparams()

public void select()

效果圖:

swagger常用註解

一 swagger常用註解 1 與模型相關的註解 兩個註解 2 與介面相關的註解 六個註解 二 幾個注意點 為了在swagger ui上看到輸出,至少需要兩個註解 api和 apioperation 即使只有乙個 apiresponse,也需要使用 apiresponses包住 對於 apiimpl...

swagger常用註解

一 swagger常用註解 1 與模型相關的註解 兩個註解 2 與介面相關的註解 六個註解 二 幾個注意點 為了在swagger ui上看到輸出,至少需要兩個註解 api和 apioperation 即使只有乙個 apiresponse,也需要使用 apiresponses包住 對於 apiimpl...

Swagger常用註解

目錄 swagger是乙個開放源 軟體框架,由大型工具生態系統支援,可幫助開發人員設計,構建,記錄和使用restful web服務。儘管大多數使用者通過swagger ui工具識別swagger,但是swagger工具集包括對自動文件,生成和測試用例生成的支援。api 註解用於標註乙個control...