swagger2常用注解
主要分两个部分,控制器和实体类的注解
环境搭建https://coderwcb.blog.csdn.net/article/details/121170908
下方有对应的代码和图片,对应起来就可以
@Api:用在请求的类上,表示对类的说明
tags="说明该类的作用,可以在UI界面上看到的注解"
value="该参数没什么意义,在UI界面上也看到,所以不需要配置"
@ApiOperation:用在请求的方法上,说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
@ApiResponses:用在请求的方法上,表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
@ApiModel:用于响应类上,表示一个返回响应数据的信息
(这种一般用在post创建的时候,使用@RequestBody这样的场景,
请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:用在属性上,描述响应类的属性
@ApiIgnore()用于类,方法,方法参数 表示这个方法或者类被忽略
完整代码实现
控制器
package com.mall.controller;
import com.mall.beans.Cate;
import com.mall.beans.RespBean;
import com.mall.service.CateService;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
/**
* <p>
* 前端控制器
* </p>
*
* @author wei
* @since 2021-11-07
*/
@Api(tags = "这是测试接口")
@RestController
@RequestMapping("/test")
public class CateController {
@Autowired
private CateService cateService;
@ApiOperation("获取所有数据")
@GetMapping("/a")
public RespBean getAll() {
return new RespBean(200, "测试", null);
}
@ApiOperation(value = "获取一条数据", notes = "必须是数字")
@GetMapping("/b")
public RespBean getOne() {
return new RespBean(200, "测试", null);
}
@ApiOperation("根据id获取数据")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "手机号", paramType = "path", defaultValue = "123456"),
@ApiImplicitParam(name = "token", value = "密钥", paramType = "header", defaultValue = "token"), // 经测试,不能使用中文
@ApiImplicitParam(name = "name", value = "名字", paramType = "query", defaultValue = "张三"),
@ApiImplicitParam(name = "age", value = "年龄", defaultValue = "20"),
@ApiImplicitParam(name = "cate", value = "类" ,paramType = "body",defaultValue = "这个默认值不生效") // 当传递一个类的时候还是不要写这个比较好,写了反倒还得修该为json
})
@PostMapping("/c/{id}")
public RespBean getOne(
@PathVariable("id") int id,
@RequestHeader String token,
@RequestParam String name,
@RequestParam String age,
@RequestBody Cate cate
) {
System.out.println(id+"=="+token+"=="+name+"=="+age+"=="+cate);
return new RespBean(200, "测试", id+"=="+token+"=="+name+"=="+age+"=="+cate);
}
@ApiOperation(value = "select1请求",notes = "多个参数,多种的查询参数类型")
@ApiResponses({
@ApiResponse(code=400,message="请求参数没填好"),
@ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})
@PostMapping("/d")
public RespBean select1(@ApiIgnore String name) {
return new RespBean(200, "测试", null);
}
}
javabean
package com.mall.beans;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;
/**
* <p>
*
* </p>
*
* @author wei
* @since 2021-11-07
*/
@ApiModel(description = "返回响应数据")
public class Cate implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "主键")
@TableId(value = "id", type = IdType.AUTO)
private Integer id;
@ApiModelProperty(value = "名字")
private String name;
private Integer pid;
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public Integer getPid() {
return pid;
}
public void setPid(Integer pid) {
this.pid = pid;
}
@Override
public String toString() {
return "Cate{" +
"id=" + id +
", name=" + name +
", pid=" + pid +
"}";
}
}
对应的图片
参考文章:
https://blog.csdn.net/u014231523/article/details/76522486?spm=1001.2101.3001.6650.2&utm_medium=distribute.pc_relevant.none-task-blog-2%7Edefault%7ECTRLIST%7Edefault-2.no_search_link&depth_1-utm_source=distribute.pc_relevant.none-task-blog-2%7Edefault%7ECTRLIST%7Edefault-2.no_search_link
https://blog.csdn.net/jiangyu1013/article/details/83107255