Swagger中@ApiIgnore註解的使用詳解

Posted on by

Swagger @ApiIgnore註解的使用

@ApiIgnore 可以用在類、方法上，方法參數中，用來屏蔽某些接口或參數，使其不在頁面上顯示。

1、作用在類上時，整個類都會被忽略

@ApiIgnore
@Api(tags = {"Xxx控制類"})
@RestController
@RequestMapping("/xxx")
public class XxxController {
  ......
}

隱藏某個類還可以用@Api註解自帶的hidden屬性：

@Api(value = "xxx", tags = "xxx",hidden = true)

當hidden為true時，該類隱藏。

2、當作用在方法上時，方法將被忽略

@ApiIgnore
@ApiOperation(value = "xxx", httpMethod = "POST", notes = "xxx")
@ApiImplicitParams({
  @ApiImplicitParam(name = "xxx", value = "xxx", paramType = "query", dataType = "String", required = true)
})
@PostMapping("/xxx")
public Result importCarryEquExcel(String xxx) {
    ......
}

隱藏某個方法還可以用@APIOperation註解自帶的hidden屬性：

@ApiOperation(value = "xxx", httpMethod = "GET", notes = "xxx",hidden = true)

當hidden為true時，該方法隱藏。

3、作用在參數上時，單個具體的參數會被忽略

public String abc(@ApiIgnore String a, String b, String c){
    return "a" + "b" + "c";
  }

補充：

4、 在實體類中忽略不需要字段的方式

（1）用@ApiModelProperty註解自帶的hidden屬性:

    @ApiModelProperty(value = "xxxid", required = true,hidden = true)
    private Long id;

（2）使用@JsonIgnore註解：

    @ApiModelProperty(value = "xxxid", required = true)
    @JsonIgnore
    private Long id;

包名：

import  com.fasterxml.jackson.annotation.JsonIgnore;

swagger 註解的使用解析

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

@ApiResponses(value = {@ApiResponse(code = 500, msg= "INTERNAL_SERVER_ERROR", response = R.class)})
@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

以分頁代碼進行展示

IPage<Notice> pages = noticeService.page(Condition.getPage(query), Condition.getQueryWrapper(notice, Notice.class));

@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 );
}

以上為個人經驗，希望能給大傢一個參考，也希望大傢多多支持WalkonNet。

推薦閱讀：