swagger注解

Swagger常用注解

@Api

• 作用于Controller类
• 标识swagger识别的类

属性	功能说明
value	值
tags	分组(说明该类的作用，tags的值会覆盖value的值)
description	描述
basePath	基本路径
position	api显示位置顺序
consumes	例如：application/json, application/xml
protocols	协议类型，如：http，https，ws，wss
authorizations	高级特征认证配置
hidden	是否隐藏

使用示例：

@Controller
@Api(tags="订单模块")
public class OrderController {
}

---

@ApiIngore

• 作用于Controller类

• 屏蔽显示某个controller，开启后在swagger上将不会显示

属性	功能说明
value	值

---

@ApiOperation

• 作用于Controller类中的方法
• 标识swagger识别的方法

属性	功能说明
value	中文描述
tags	分组
notes	方法的备注说明
position	api显示位置顺序
produces	例如：application/json,application/xml
consumes	例如：application/json, application/xml
protocols	例如：http, https, ws, wss.
authorizations	高级特性认证
hidden	配置为true 将在文档中隐藏
response	返回的对象
responseContainer	可选参数：List、Set、Map，其他无效
httpMethod	GET、HEAD、POST、PUT、DELETE、OPTIONS、PATCH
code	状态码，默认为200
extensions	扩展属性

@ApiImplicitParam

• 作用于方法或方法入参
• 修饰方法中的入参参数

属性	功能说明
name	英文描述
value	中文描述
dataType	参数数据类型(默认String)，可传基本类型、类、泛型类等。
paramType	参数传递形式，如body、header等
defaultValue	参数的默认值
required	是否必须

• dataType

  基本类型、类按照正常来赋值，则定义泛型类应该按照如下格式类赋值：

  dataType = “demo<<ArrayList<<demo1>>>>”

  对应类为demo<demo1[]>

• paramType

  • path：以地址的形式提交数据(用于restful接口)
  • query：直接跟参数完成自动映射赋值
  • body：以流的形式提交，支持POST
  • header：参数在request headers中提交
  • from：以form表单的形式提交，仅支持POST

  注意：paramType指定的参数获取方式必须与spring指定的方法参数获取值方式必须一致，否则影响参数的接收。

  @ApiImplicitParam(ParamType="header",...)
  public String get(@RequestParam Integer id){
      /*
      以上情况swagger注解和spring注解分别制定了不同的参数接收方式，这会到时参数接收不到
      */
  }
  

path

@RequestMapping(value = "/urlAddress/{id}", method = RequestMethod.GET)
public void getID_1(@PathVariable(name = "id") Long id){
}

body

@ApiImplicitParam(paramType = "body", dataType = "ActDeploymentUpdQry", name = "actDeploymentUpdQry", value = "参数名称", required = true)
@ReqestMapping(value="/urlAddress", method=REquestMethod.POST)
public Result<Boolean> updActDeployment(@RequestBody ActDeploymentUpdQry actDeploymentUpdQry){
    return new Result<>();
}

header

@ApiImplicitParam(paramType = "header", dataType = "Long", name = "id", value = "参数名称", required = true)
public void getID_2(){
    Long id = StringUtils.isNumeric(request.getHesaders("id"));
}

form

@ApiImplicitParam(paramType = "form", dataType = "Long", name = "id", value = "参数名称", required = true)
@RequestMapping(value = "/urlAddress", method = RequestMethod.POST)
//TODO:???

@ApiImplicitParams

• 作用于方法或方法入参
• 修饰方法中的入参参数

属性	功能说明
@ApiImplicitParam

使用示例：

@ApiOperation(value="用户登录",notes="随边说点啥")
@ApiImplicitParams({
	@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
    @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
    @ApiImplicitParam(name="age",value="年龄",paramType="form",dataType="Integer")})
    @PostMapping("/login")
    public JsonResult login(@RequestParam String mobile, @RequestParam String password,@RequestParam Integer age){
        //...
        return JsonResult.ok(map);
    }

---

@ApiResponse

• 作用于方法或方法入参
• 修饰方法的返回值

属性	功能说明
code	方法返回值状态码
message	方法返回值信息
class	方法返回class
response	抛出的异常类

@ApiResponses

• 作用于方法或方法入参
• 修饰方法的返回值

属性	功能说明
@ApiResponse	ApiResponse的数组集合

使用示例：

@ApiOperation("获取用户信息")
@ApiImplicitParam(paramType="query", name="userId", dataType="String",value="用户Id")
@ApiResponses({
    @ApiResponse(code = 400, message = "请求参数没填好"),
    @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")}) 
@RequestMapping("/list"，method=RequestMethod.POST)
    public JsonResult list(@RequestBody String userId) {
        ...
        return JsonResult.ok().put("page", pageUtil);
    }

---

@ApiParam

• 作用于方法的入参
• 映射方法的入参

属性	功能说明
name	名称
value	简单描述
defaultValue	参数值默认值
allowableValues	可接收参数限制
required	是否为必传参数
access	参数过滤，参阅:io.swagger.core.filter.SwaggerSpecFilter
allowMultiple	指定参数是否可以通过多次出现来接收多个值
hidden	隐藏参数列表中的参数
example	非请求体(body)类型的单个参数示例
examples	参数示例，仅适用于请求体类型的请求

---

@ApiModel

• 作用于JavaBean类
• 标识一个类为model

属性	功能说明
value	值
description	描述

@ApiModelProperty

• 作用与JavaBean类的属性
• 标识一个JavaBean类的属性

属性	功能说明
value	值
name	名字
required	是否必须(默认false)

使用标识：

@ApiModel(descriptoin="应用类型实体数据")
public class ApplyTypeEntity extends BaseEntity implements Serializable {
    private static final long serialVersionUID = 5673951458714866692L;
    @ApiModelProperty(value = "申请类型ID", name = "applyTypeId")
    private String applyTypeId;
    @ApiModelProperty(value = "上级申请类型ID", name = "applyTypeParentId")
    private String applyTypeParentId;
    @ApiModelProperty(value = "申请类型编码(字符串命名，自动生成)", name = "typeCode")
    private String typeCode;
    @ApiModelProperty(value = "申请类型名字(中文命名)", name = "typeName")
    private String typeName;
    @ApiModelProperty(value = "申请类型的备注信息", name = "remark")
    private String remark;
    @ApiModelProperty(value = "启用标志位，开启：Y，关闭：N", name = "useable")
    private String useable;
    /*省略get和set方法*/
}

---

网络资源：

https://blog.csdn.net/xupeng874395012/article/details/68946676

https://my.oschina.net/dlam/blog/808315