swagger 常用注解

swagger2 注解整體說明

用于controller類上：

注解	說明
@Api	對請求類的說明

用于方法上面（說明參數的含義）：

注解	說明
@ApiOperation	方法的說明
@ApiImplicitParams、@ApiImplicitParam	方法的參數的說明；@ApiImplicitParams 用于指定單個參數的說明

用于方法上面（傳回參數或對象的說明）：

注解	說明
@ApiResponses、@ApiResponse	方法傳回值的說明 ；@ApiResponses 用于指定單個參數的說明

對象類：

注解	說明
@ApiModel	用在JavaBean類上，說明JavaBean的 用途
@ApiModelProperty	用在JavaBean類的屬性上面，說明此屬性的的含議

@Api：請求類的說明

···

@Api：放在 請求的類上，與 @Controller 并列，說明類的作用，如使用者子產品，訂單類等。

tags=“說明該類的作用”

value=“該參數沒什麼意義，是以不需要配置”

···

示例：

···

@Api(tags=“訂單子產品”)

@Controller

public class OrderController {

}

···

@Api 其它屬性配置：

屬性名稱	備注
value	url的路徑值
tags	如果設定這個值、value的值會被覆寫
description	對api資源的描述
basePath	基本路徑
position	如果配置多個Api 想改變顯示的順序位置
produces	如, “application/json, application/xml”
consumes	如, “application/json, application/xml”
protocols	協定類型，如: http, https, ws, wss.
authorizations	進階特性認證時配置
hidden	配置為true ，将在文檔中隐藏

@ApiOperation：方法的說明

@ApiOperation："用在請求的方法上，說明方法的作用"
  value="說明方法的作用"
  notes="方法的備注說明"      

@ApiImplicitParams、@ApiImplicitParam：方法參數的說明

@ApiImplicitParams：用在請求的方法上，包含一組參數說明
  @ApiImplicitParam：對單個參數的說明      
      name：參數名
      value：參數的說明、描述
      required：參數是否必須必填
      paramType：參數放在哪個地方
          · query --> 請求參數的擷取：@RequestParam
          · header --> 請求參數的擷取：@RequestHeader        
          · path（用于restful接口）--> 請求參數的擷取：@PathVariable
          · body（請求體）-->  @RequestBody User user
          · form（普通表單送出）     
      dataType：參數類型，預設String，其它值dataType="Integer"     
      defaultValue：參數的預設值      

示列：

@Api(tags="使用者子產品")
@Controller
public class UserController {

  @ApiOperation(value="使用者登入",notes="随邊說點啥")
  @ApiImplicitParams({
    @ApiImplicitParam(name="mobile",value="手機号",required=true,paramType="form"),
    @ApiImplicitParam(name="password",value="密碼",required=true,paramType="form"),
    @ApiImplicitParam(name="age",value="年齡",required=true,paramType="form",dataType="Integer")
  })
  @PostMapping("/login")
  public JsonResult login(@RequestParam String mobile, @RequestParam String password,
  @RequestParam Integer age){
    //...
      return JsonResult.ok(map);
  }
}      

@ApiResponses、@ApiResponse：方法傳回值的狀态碼說明

@ApiResponses：方法傳回對象的說明
  @ApiResponse：每個參數的說明
      code：數字，例如400
      message：資訊，例如"請求參數沒填好"
      response：抛出異常的類      

示例：

@Api(tags="使用者子產品")
@Controller
public class UserController {

  @ApiOperation("擷取使用者資訊")
  @ApiImplicitParams({
    @ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="使用者Id")
  }) 
  @ApiResponses({
    @ApiResponse(code = 200, message = "請求成功"),
    @ApiResponse(code = 400, message = "請求參數沒填好"),
    @ApiResponse(code = 404, message = "請求路徑沒有或頁面跳轉路徑不對")
  }) 
  @ResponseBody
  @RequestMapping("/list")
  public JsonResult list(@RequestParam String userId) {
    ...
    return JsonResult.ok().put("page", pageUtil);
  }
}      

@ApiModel：用于JavaBean上面，表示對JavaBean 的功能描述

@ApiModel的用途有2個：

當請求資料描述時， @RequestBody 時的使用

@ApiModel(description = "使用者登入")
public class UserLoginVO implements Serializable {

  private static final long serialVersionUID = 1L;

  @ApiModelProperty(value = "使用者名",required=true)  
  private String username;

  @ApiModelProperty(value = "密碼",required=true) 
  private String password;
  
  // getter/setter省略
}      

@Api(tags="使用者子產品")
@Controller
public class UserController {

  @ApiOperation(value = "使用者登入", notes = "") 
  @PostMapping(value = "/login")
  public R login(@RequestBody UserLoginVO userLoginVO) {
    User user=userSerivce.login(userLoginVO);
    return R.okData(user);
  }
}      

@ApiModelProperty：用在JavaBean類的屬性上面，說明屬性的含義

@ApiModel(description= "傳回響應資料")
public class RestMessage implements Serializable{

    @ApiModelProperty(value = "是否成功",required=true)
    private boolean success=true;   
    
    @ApiModelProperty(value = "錯誤碼")
    private Integer errCode;
    
    @ApiModelProperty(value = "提示資訊")
    private String message;
    
    @ApiModelProperty(value = "資料")
    private Object data;
        
    /* getter/setter 略*/
}