Swagger2常用注解及其說明 （轉）

Api

　　用在Controller中，標記一個Controller作為swagger的文檔資源

屬性名稱	說明
value	Controller的注解
description	對api資源的描述
hidden	配置為true 將在文檔中隱藏

 

 

 

 

 

使用方法：

@Api(value = "登錄服務",description = "用戶登錄相關接口")
@RestController("loginControllerLayui")
@RequestMapping("/login")
public class LoginController {
}

ApiOperation

  該注解用在Controller的方法中，用於注解接口

屬性名稱	說明
value	接口的名稱
notes	接口的注釋
response	接口的返回類型，比如說：response = String.class
hidden	配置為true 將在文檔中隱藏

 

 

 

 

 

 

使用方法：

@ApiOperation(value = "獲取驗證碼圖片",notes = "每調用一次，就會隨機生成一張驗證碼圖片",response = String.class)
    @GetMapping("/verifyCode.img")
    public String getVerifyCode(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException{
    }

ApiParam

  該注解用在方法的參數中。

屬性名稱	說明
name	參數名稱
value	參數值
required	是否必須，默認false
defaultValue	參數默認值
type	參數類型
hidden	隱藏該參數

 

 

 

 

 

 

 

使用方法：

@ApiOperation(value = "添加權限",notes = "插入權限",response = JsonData.class)
    @PostMapping("/insertAcl.json")
    public JsonData insertAcl(@ApiParam(name = "param",value = "實體類AclParam",required = true) AclParam param){
}

ApiResponses/ApiResponse

  該注解用在Controller的方法中，用於注解方法的返回狀態。

屬性名稱	說明
code	http的狀態碼
message	狀態的描述信息
response	狀態相應，默認響應類 Void

  

 

 

 

 

使用方法：

@ApiOperation(value = "菜單",notes = "進入菜單界面",nickname = "菜單界面")
    @ApiResponses({
            @ApiResponse(code = 200,message = "成功！"),
            @ApiResponse(code = 401,message = "未授權！"),
            @ApiResponse(code = 404,message = "頁面未找到！"),
            @ApiResponse(code = 403,message = "出錯了！")
    })
    @GetMapping("/aclModule.page")
    public ModelAndView aclModule(Model model){
    }

ApiModel

  該注解用在實體類中。

屬性名稱	說明
value	實體類名稱
description	實體類描述
parent	集成的父類，默認為Void.class
subTypes	子類，默認為{}
reference	依賴，默認為“”

  

 

 

 

 

 

使用方法：

@ApiModel(value = "JsonData",description = "返回的數據類型")
public class JsonData {
}

ApiImplicitParams/ApiImplicitParam

  該注解用在Controller的方法中，同ApiParam的作用相同，但是比較建議使用ApiParam。

屬性名稱	說明
name	參數名稱
value	參數值
defaultValue	參數默認值
required	是否必須
allowMultiple	是否允許重復
dataType	數據類型
paramType	參數類型

  

 

 

 

 

 

 

 

 

使用方法：

@ApiOperation(value = "創建用戶",notes = "根據User對象創建用戶")
    @ApiImplicitParam(name = "user",value = "用戶詳細實體user")
    @RequestMapping(value="/", method=RequestMethod.POST)
    public String postUser(@ModelAttribute User user){
    }

 

ApiModelProperty

  該注解用在實體類的字段中。

屬性名稱	說明
name	屬性名稱
value	屬性值
notes	屬性注釋
dataType	數據類型，默認為“”
required	是否必須，默認為false
hidden	是否隱藏該字段，默認為false
readOnly	是否只讀，默認false
reference	依賴，，默認“”
allowEmptyValue	是否允許空值，默認為false
allowableValues	允許值，默認為“”

 

 

 

 

 

 

 

 

 

 

 

使用方法：

//返回狀態信息
    @ApiModelProperty(name = "code",value = "狀態code",notes = "返回信息的狀態")
    private int code;
    //返回攜帶的信息內容
    @ApiModelProperty(name = "msg",value = "狀態信息",notes = "返回信息的內容")
    private String msg = "";
    //返回信息的總條數
    @ApiModelProperty(name = "count",value = "查詢數量",notes = "返回信息的條數")
    private int count;
    //返回對象
    @ApiModelProperty(name = "data",value = "查詢數據",notes = "返回數據的內容")
    private Object data;