标签：构建 rip ams parameter 主键 rest 小项目 演示 参数
今天做一个小项目时用到了Swagger2，所以写篇随笔来记录一下.Swagger2的优点我就不多说了。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
@Configuration
@EnableSwagger2
public class Swagger2Config {
/**
* @Description:swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
*/
@Bean
public Docket createRestApi() {
// 为swagger添加header参数可供输入
ParameterBuilder userTokenHeader = new ParameterBuilder();
ParameterBuilder userIdHeader = new ParameterBuilder();
List<Parameter> pars = new ArrayList<Parameter>();
userTokenHeader.name("headerUserToken").description("userToken")
.modelRef(new ModelRef("string")).parameterType("header")
.required(false).build();
userIdHeader.name("headerUserId").description("userId")
.modelRef(new ModelRef("string")).parameterType("header")
.required(false).build();
pars.add(userTokenHeader.build());
pars.add(userIdHeader.build());
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
.apis(RequestHandlerSelectors.basePackage("com.gt.video.controller")) //要扫描的包
.paths(PathSelectors.any()).build()
.globalOperationParameters(pars);
}
/**
* @Description: 构建 api文档的信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 设置页面标题
.title("使用swagger2构建短视频后端api接口文档")
// 设置联系人
.contact(new Contact("gttttttt", "https://www.cnblogs.com/gttttttt", "2933253458@qq.com"))
// 描述
.description("欢迎访问短视频接口文档，这里是描述信息")
// 定义版本号
.version("1.0").build();
}
}
在Controller和pojo类上编写注解，为了方便演示，我们这里编写用户注册的Contrller
@RestController
@Api(value = "用户注册和登陆的接口",tags = {"用户注册和登陆的Controller"})
public class RegistLoginController {
@Autowired
UsersService usersService;
@PostMapping("/regist")
@ApiOperation(value = "用户注册",notes = "用户注册的接口")
public R regist(@RequestBody UsersEntity users) throws Exception {
//1.判断用户名或密码是否为空
if(StringUtils.isBlank(users.getUsername()) || StringUtils.isBlank(users.getPassword())){
return R.error("用户名或密码不能为空");
}
//2.查询用户名是否存在
QueryWrapper<UsersEntity> wrapper = new QueryWrapper<UsersEntity>();
wrapper.eq("username",users.getUsername());
UsersEntity usersEntity = usersService.getOne(wrapper);
if(usersEntity!=null){
return R.error("用户名已经存在了,请换一个吧");
}
//3.将用户信息保存在数据库
users.setId(UUID.randomUUID().toString().replaceAll("-",""));
users.setPassword(MD5Utils.getMD5Str(users.getPassword()));
users.setFollowCounts(0);
users.setReceiveLikeCounts(0);
users.setFansCounts(0);
users.setNickname(users.getUsername());
usersService.save(users);
users.setPassword("");
return R.ok("注册成功").put("code",200).put("data",users);
}
}
//这里使用了Lombok和Mybatisplus
@Data
@TableName("users")
@ApiModel(value = "用户对象",description = "这是用户对象")
public class UsersEntity implements Serializable {
private static final long serialVersionUID = 1L;
/**
* 主键ID
*/
@TableId
private String id;
/**
* 用户名
*/
//name对应字段名，example为示例，required表示必填
@ApiModelProperty(value = "用户名",name ="username",example = "gttttttt",required = true)
private String username;
/**
* 密码
*/
@ApiModelProperty(value = "密码",name ="password",example = "1234567",required = true)
private String password;
/**
* 用户照片
*/
@ApiModelProperty(hidden = true) //表示提交请求时，该字段可以忽略不写
private String faceImage;
/**
* 用户名
*/
@ApiModelProperty(hidden = true)
private String nickname;
/**
*
*/
@ApiModelProperty(hidden = true)
private Integer fansCounts;
/**
*
*/
@ApiModelProperty(hidden = true)
private Integer followCounts;
/**
* $column.comments
*/
@ApiModelProperty(hidden = true)
private Integer receiveLikeCounts;
}
响应结果:
因为篇幅有限，所以截的图片不是很好。
@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：用在属性上，描述响应类的属性
本篇随笔参考以下博客:
万分感谢!!!
标签：构建 rip ams parameter 主键 rest 小项目 演示 参数
原文地址：https://www.cnblogs.com/gttttttt/p/13576503.html
