# :-: Swagger ## 簡介 * 由于架構革新，進入了前后端分離，服務端只需提供RESTful API的時代。 * 而構建RESTful API會考慮到多終端的問題，這樣就需要面對多個開發人員甚至多個開發團隊。 * 為了減少與其他團隊對接的溝通成本，我們通常會寫好對應的API接口文檔。 * 從最早開始的word文檔，到后續的showdoc，都能減少很多溝通成本，但隨之帶來的問題也比較麻煩。在開發期間接口會因業務的變更頻繁而變動，如果需要實時更新接口文檔，這是一個費時費力的工作。 * 為了解決上面的問題，Swagger應運而生。他可以輕松的整合進框架，并通過一系列注解生成強大的API文檔。他既可以減輕編寫文檔的工作量，也可以保證文檔的實時更新，將維護文檔與修改代碼融為一體，是目前較好的解決方案。 ## 常用注解 * @Api()用于類； 表示標識這個類是swagger的資源 * @ApiOperation()用于方法； 表示一個http請求的操作 * @ApiParam()用于方法，參數，字段說明； 表示對參數的添加元數據（說明或是否必填等） * @ApiModel()用于類 表示對類進行說明，用于參數用實體類接收 * @ApiModelProperty()用于方法，字段 表示對model屬性的說明或者數據操作更改 * @ApiIgnore()用于類，方法，方法參數 表示這個方法或者類被忽略 * @ApiImplicitParam() 用于方法 表示單獨的請求參數 * @ApiImplicitParams() 用于方法，包含多個 @ApiImplicitParam ## 代碼示例 1. `@Api` ~~~ @Api(value = "用戶博客", tags = "博客接口") public class NoticeController { } ~~~ 2. `@ApiOperation` ~~~ @GetMapping("/detail") @ApiOperation(value = "獲取用戶詳細信息", notes = "傳入notice" , position = 2) public R<Notice> detail(Integer id) { Notice detail = noticeService.getOne(id); return R.data(detail ); } ~~~ 3. `@ApiResponses` ~~~ @GetMapping("/detail") @ApiOperation(value = "獲取用戶詳細信息", notes = "傳入notice" , position = 2) @ApiResponses(value = {@ApiResponse(code = 500, msg= "INTERNAL_SERVER_ERROR", response = R.class)}) public R<Notice> detail(Integer id) { Notice detail = noticeService.getOne(id); return R.data(detail ); } ~~~ 4. `@ApiImplicitParams` ~~~ @GetMapping("/list") @ApiImplicitParams({ @ApiImplicitParam(name = "category", value = "公告類型", paramType = "query", dataType = "integer"), @ApiImplicitParam(name = "title", value = "公告標題", paramType = "query", dataType = "string") }) @ApiOperation(value = "分頁", notes = "傳入notice", position = 3) public R<IPage<Notice>> list(@ApiIgnore @RequestParam Map<String, Object> notice, Query query) { IPage<Notice> pages = noticeService.page(Condition.getPage(query), Condition.getQueryWrapper(notice, Notice.class)); return R.data(pages ); } ~~~ 5. `@ApiParam` ~~~ @PostMapping("/remove") @ApiOperation(value = "邏輯刪除", notes = "傳入notice", position = 7) public R remove(@ApiParam(value = "主鍵集合") @RequestParam String ids) { boolean temp = noticeService.deleteLogic(Func.toIntList(ids)); return R.status(temp); } ~~~ 6. `@ApiModel`與`@ApiModelProperty` ~~~ @Data @ApiModel(value = "BladeUser ", description = "用戶對象") public class BladeUser implements Serializable { private static final long serialVersionUID = 1L; @ApiModelProperty(value = "主鍵", hidden = true) private Integer userId; @ApiModelProperty(value = "昵稱") private String userName; @ApiModelProperty(value = "賬號") private String account; @ApiModelProperty(value = "角色id") private String roleId; @ApiModelProperty(value = "角色名") private String roleName; } ~~~ 7. `@ApiIgnore()` ~~~ @ApiIgnore() @GetMapping("/detail") public R<Notice> detail(Integer id) { Notice detail = noticeService.getOne(id); return R.data(detail ); } ~~~