Swagger使用纪要

一、常用注解说明

1、@Api

@Api:用在请求的类上,表示对类的说明
    tags="说明该类的作用,可以在UI界面上看到的注解"
    value="该参数没什么意义,在UI界面上也看不到,所以不需要配置"

在这里插入图片描述

2、@ApiOperation

@ApiOperation:用在请求的方法上,说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

在这里插入图片描述

3、@ApiImplicitParams

1)注解基础说明

@ApiImplicitParams:用在请求的方法上,表示一组参数说明
    @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
        name:参数名
        value:参数的汉字说明、解释
        required:参数是否必须传
        paramType:参数放在哪个地方
            · header --> 请求参数的获取:@RequestHeader
            · query --> 请求参数的获取:@RequestParam
            · path(用于restful接口)--> 请求参数的获取:@PathVariable
            · body(不常用)
            · form(不常用)    
        dataType:参数类型,默认String,其它值dataType="Integer"       
        defaultValue:参数的默认值

在这里插入图片描述

2)@ApiImplicitParam属性dataType单独使用会出现的bug说明

  • 问题描述

如果你的项目模块,swagger配置了分组,如下图
在这里插入图片描述

其效果
在这里插入图片描述
这时,swagger有一个非常坑的bug:你的注解@ApiImplicitParam属性dataType,不能单独使用,否则会引起一个前端错误、导致当前分组Api文档无法显示(页面会停留在点击前的页面、不跳转)。
bug截图
在这里插入图片描述

  • 解决方式
    如果要设置分组,那么使用@ApiImplicitParam注解时,dataType属性要么不使用,要么就和paramType属性一起使用
    这个应该时swagger的一个bug,并没有逻辑性,我是通过一次一次测试得到的结果。(花了整整一天时机做这种没意义的事,希望大家不用重蹈覆辙~)
    下面把测试截图记录一下,当时已知name和value属性是干净的,dataType单独使用不行、必须和paramType组合使用:
    a、怀疑是dataType位置导致的,做以下测试,发现bug没有修复;
    在这里插入图片描述
    b、又想是不是dataType和required属性组合也可以,做以下测试,bug没有修复
    在这里插入图片描述
    b、经测试,配置分组后@ApiImplicitParam注解的dataType属性就只能和paramType属性一起使用,或者不使用;单独使用就会引发上述错误。与属性先后顺序(位置)无关。

3.5、@ApiImplicitParams常用配套参数@ApiIgnore和@ApiModelProperty属性hidden

1)痛点

使用@ApiImplicitParam注解备注参数后,文档会有这样的问题:就是注解的备注会显示,方法形参也会显示(名称相同就显示一个)。这样会导致api文档特别冗余,很难读、还容易引发歧义,而且与我们的初衷也不相符,我都用@ApiImplicitParam注解了,肯定是希望以注解的备注为准啊,形参的显示混淆了视听。
在这里插入图片描述
在这里插入图片描述

2)解决

这时我们肯定想,其实不是入参的字段在swagger文档中隐藏掉;可以用以下几种方法。(隐藏,是指不在swagger接口文档中显示)
a、使用@ApiIgnore注解(最简单实用)
该注解用在方法的形参列表,它会将其后的参数隐藏掉;如果注解后是一个实体类,那么该实体类的所有字段都会被隐藏。
在这里插入图片描述
在这里插入图片描述
b、使用@ApiModelProperty的hidden属性
如果你的接口参数是用实体类接收的,那么你可以在字段上使用@ApiModelProperty注解,并将其属性hidden值设为true,这样该字段就会在swagger文档上隐藏了。
但是这个方法有个问题,当实体类字段特别多时,那你就需要加非常多@ApiModelProperty注解才能把它们全部隐藏。
不过它也有适用场景,当你不用@ApiImplicitParam注解备注接口入参、就用@ApiModelProperty注解备注时,你就可以用hidden属性将实体类中不是入参的其他字段隐藏掉。
在这里插入图片描述

4、@ApiModel

@ApiModel:用于类,表示对类进行说明,用于参数用实体类接收 
	value:表示对象名 
	description:描述 

在这里插入图片描述
在这里插入图片描述

5、@ApiModelProperty

@ApiModelProperty:用于字段; 表示对model属性的说明或者数据操作更改 
	value:字段说明 
	name:重写属性名字(实测没什么用,seagger会自动强制写属性名) 
	dataType:重写属性类型 (也没什么用,seagger会自动强制写属性类型)
	required:是否必填,Boolean类型,默认flase(必填字段会有个*)
	example:举例说明(可以给一个字段值示例)
	hidden:是否隐藏,Boolean类型,默认flase

在这里插入图片描述

6、@ApiModel

@ApiModel:用于响应类上,表示一个返回响应数据的信息
            (这种一般用在post创建的时候,使用@RequestBody这样的场景,
            请求参数无法使用@ApiImplicitParam注解进行描述的时候)
    @ApiModelProperty:用在属性上,描述响应类的属性
  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值