Knife4j 注解詳談

Controller層添加注解

@Api:用於類；表示標識這個類是swagger的資源

 

屬性名稱	數據類型	默認值	說明
value	String	""	字段說明
tags	String[]	""	標簽說明
description	String	""	詳情描述
basePath	String	""	基本路徑可以不配置
position	int	""	如果配置多個Api 想改變顯示的順序位置
produces	String	""	提供者 (For example, "application/json, application/xml")
consumes	String	""	消費者(For example, "application/json, application/xml")
protocols	String	""	協議(Possible values: http, https, ws, wss.)
authorizations	Authorization[]	""	高級特性認證時配置
hidden	boolean	""	配置為true 將在文檔中隱藏

使用實例:

注解加載在controller類上

常用模型:

@Api(tags = "HELLO CONTROLLER 測試功能接口")
@RestController
public class HelloController {

}

 

@ApiResponses:在 Rest 接口上使用，用作返回值的描述

參數

屬性名稱	數據類型	默認值	說明
value	ApiResponse[]	""	訪問對象

ApiResponse參數

屬性名稱	數據類型	默認值	說明
code	String	""	響應的HTTP狀態碼
message	String	""	響應的信息內容
response	Class<?>	""	用於描述消息有效負載的可選響應類，對應於響應消息對象的 schema 字段
reference	String	""	指定對響應類型的引用，指定的應用可以使本地引用，也可以是遠程引用，將按原樣使用，並將覆蓋任何指定的response()類
responseHeaders	ResponseHeader[]	""	聲明包裝響應的容器，有效值為List或Set，任何其他值都將被覆蓋
responseContainer	String	""	聲明響應的容器，有效值為List,Set,Map，任何其他值都將被忽略
examples	Example	""	例子

使用實例:

注解加載在字段上

常用模型:

  @ApiResponses(value = {
            @ApiResponse(code = 200, message = "接口返回成功狀態"),
            @ApiResponse(code = 500, message = "接口返回未知錯誤，請聯系開發人員調試")
    })
    @PostMapping("hello")
    public Results<UserVO> hello(@RequestBody UserVO userVO){

        Results<UserVO> results = new Results<>(200,"SUCCESS", userVO);
        return results;
    }

 

@ApiOperation:用在方法上，說明方法的作用，每一個url資源的定義

參數

屬性名稱	數據類型	默認值	說明
value	String	""	url的路徑值
notes	String	""	文本說明
tags	String[]	""	如果設置這個值、value的值會被覆蓋
response	Class<?>	""	返回的對象
responseContainer	String	""	聲明響應的容器，有效值為List,Set,Map，任何其他值都將被忽略
responseReference	String	""	聲明包裝響應的容器，有效值為List或Set，任何其他值都將被覆蓋
httpMethod	String	""	"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
position	int	""	如果配置多個Api 想改變顯示的順序位置
nickname	String	""	昵稱
produces	String	""	提供者 (For example, "application/json, application/xml")
consumes	String	""	消費者(For example, "application/json, application/xml")
protocols	String	""	協議(Possible values: http, https, ws, wss.)
authorizations	Authorization[]	""	高級特性認證時配置
hidden	boolean	""	隱藏
responseHeaders	ResponseHeader[]	""	聲明包裝響應的容器，有效值為List或Set，任何其他值都將被覆蓋
code	String	""	http的狀態碼 默認 200
extensions	Extension[]	""	擴展屬性
ignoreJsonView	boolean	""	是否忽略顯示

使用實例:

注解加載在字段上

常用模型:

 @ApiOperation(value = "Hello 測試接口", notes = "訪問此接口，返回hello語句，測試接口")
    @PostMapping("hello")
    public Results<UserVO> hello(@RequestBody UserVO userVO){

        Results<UserVO> results = new Results<>(200,"SUCCESS", userVO);
        return results;
    }

 

@PathVariable:是獲取get方式，url后面參數，進行參數綁定(單個參數或兩個以內參數使用)

參數

屬性名稱	數據類型	默認值	說明
value	String	""	url的路徑值
name	String	""	重寫屬性名字
required	String	""	是否必填

使用實例:

注解加載在字段上

常用模型:

 @ApiResponses(value = {
            @ApiResponse(code = 200, message = "接口返回成功狀態"),
            @ApiResponse(code = 500, message = "接口返回未知錯誤，請聯系開發人員調試")
    })
    @ApiOperation(value = "獲取用戶信息", notes = "訪問此接口，返回用戶信息")
    @PostMapping("/getUser/{id}")
    public String getUser(@PathVariable String id) throws InterruptedException {
        // 業務...
        return "";
    }

 

@RequestBody :在當前對象獲取整個http請求的body里面的所有數據(兩個以上參數封裝成對象使用)

參數

屬性名稱	數據類型	默認值	說明
required	String	""	是否必填

使用實例:

注解加載在傳入參數對象上

常用模型:

@ApiResponses(value = {
            @ApiResponse(code = 200, message = "接口返回成功狀態"),
            @ApiResponse(code = 500, message = "接口返回未知錯誤，請聯系開發人員調試")
    })
    @ApiOperation(value = "Hello 測試接口", notes = "訪問此接口，返回hello語句，測試接口")
    @PostMapping("hello")
    public Results<UserVO> hello(@RequestBody UserVO userVO){
        Results<UserVO> results = new Results<>(200,"SUCCESS", userVO);
        return results;
    }