Swagger中@ApiIgnore注解的使用详解

更新时间：2021年10月20日 17:08:53 作者：周公解码

这篇文章主要介绍了Swagger中@ApiIgnore注解的使用，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教

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

以上为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。

您可能感兴趣的文章:

springboot如何读取模板文件
这篇文章主要介绍了springboot如何读取模版文件的操作，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2021-09-09
springcloud微服务之Eureka配置详解
这篇文章主要介绍了springcloud微服务之Eureka配置详解，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
2020-08-08
Maven项目继承实现过程图解
这篇文章主要介绍了Maven项目继承实现过程图解,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
2020-08-08
java多线程之定时器Timer的使用详解
本篇文章主要介绍了java多线程之定时器Timer的使用详解，Time类主要负责完成定时计划任务的功能,有兴趣的可以了解一下。
2017-04-04
剑指Offer之Java算法习题精讲求和篇
跟着思路走，之后从简单题入手，反复去看，做过之后可能会忘记，之后再做一次，记不住就反复做，反复寻求思路和规律，慢慢积累就会发现质的变化
2022-03-03
MyBatis常用标签大全
这篇文章主要介绍了MyBatis常用标签大全的相关资料,非常不错，具有参考借鉴价值，需要的朋友可以参考下
2016-12-12
Java中的异常处理用法及其架构和使用建议
Java同样也提供了抛出异常、捕捉异常和finally语句的使用来处理程序异常,下面就来具体看一下Java中的异常处理用法及其架构和使用建议:
2016-06-06
MyBatis中使用#{}和${}占位符传递参数的各种报错信息处理方案
这篇文章主要介绍了MyBatis中使用#{}和${}占位符传递参数的各种报错信息处理方案,分别介绍了两种占位符的区别，本文给大家介绍的非常详细，需要的朋友可以参考下
2024-01-01
Java常用锁synchronized和ReentrantLock的区别
这篇文章主要介绍了Java常用锁synchronized和ReentrantLock的区别，二者的功效都是相同的，但又有很多不同点，下面我们就进入文章了解具体的相关内容吧。需要的小伙伴也可以参考一下
2022-05-05
java中进程与线程_三种实现方式总结(必看篇)
下面小编就为大家带来一篇java中进程与线程_三种实现方式总结(必看篇)。小编觉得挺不错的，现在就分享给大家，也给大家做个参考。一起跟随小编过来看看吧
2017-06-06