swagger2
- 什么是swagger2?
swagger2是在前后端分离的时候为前端提供开发文档,和简单的传参测试。
1.导包
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
我这使用maven统一管理jar包,在pom.xml中加入上面两个dependency,maven就能自动下载对应jar包,不了解maven的小伙伴自行在百度上找jar包,然后手动导入项目。
springfox-swagger2-vesion.jar
springfox-swagger-ui-vesion.jar
2.写一个swagger配置类
package com.imooc;
import java.util.ArrayList;
import java.util.List;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2 {
/**
* @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.imooc.controller"))
.paths(PathSelectors.any()).build();
// .globalOperationParameters(pars);
}
/**
* @Description: 构建 api文档的信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 设置页面标题
.title("使用swagger2构建短视频后端api接口文档")
// 设置联系人
.contact(new Contact("你的酷酷", "http://www.imooc.com", "imooc@163.com"))
// 描述
.description("欢迎访问短视频接口文档,这里是描述信息")
// 定义版本号
.version("1.0").build();
}
}
注解 | 含义 |
---|---|
@EnableSwagger2 | swagger2启动注解 |
@Configuration | 声明这是一个配置类 |
如上代码所示,通过 @Configuration 注解,让 Spring 加载该配置类。再通过 @EnableSwagger2 注解来启用Swagger2。成员方法 createRestApi 函数创建 Docket 的Bean之后,apiInfo() 用来创建该 Api 的基本信息(这些基本信息会展现在文档页面中)。select() 函数返回一个 ApiSelectorBuilder实例用来控制哪些接口暴露给 Swagger 来展现,本例采用指定扫描的包路径来定义,Swagger 会扫描该包下所有 Controller 定义的 API,并产生文档内容(除了被 @ApiIgnore 指定的请求)。
3.API 接口编写
package com.imooc.controller;
import java.util.UUID;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.BeanUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import com.imooc.pojo.Users;
import com.imooc.pojo.vo.UsersVO;
import com.imooc.service.UserService;
import com.imooc.utils.IMoocJSONResult;
import com.imooc.utils.MD5Utils;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
@RestController
@Api(value="用户注册登录的接口",tags= {"注册和登录的controller"})
public class RegistLoginController extends BasicController{
@Autowired
private UserService userService;
@ApiOperation(value="用户注册" ,notes="用户注册接口")
@PostMapping("/regist")
public IMoocJSONResult regist(@RequestBody Users user) throws Exception{
//1.判断用户名字和密码不为空
if(StringUtils.isBlank(user.getUsername())||StringUtils.isBlank(user.getPassword())) {
return IMoocJSONResult.errorMsg("用户名字密码不为空");
}
//2.用户名字是否存在
boolean usernameIsExit=userService.queryUsernameIsExist(user.getUsername());
if(!usernameIsExit) {
user.setNickname(user.getUsername());
user.setPassword(MD5Utils.getMD5Str(user.getPassword()));
user.setFansCounts(0);
user.setReceiveLikeCounts(0);
user.setFollowCounts(0);
userService.saveUser(user);
}else {
return IMoocJSONResult.errorMsg("用户姓名存在,请在换一个试试");
}
//3.保存用户注册信息
user.setPassword("");
// String uniqueToken =UUID.randomUUID().toString();
// redis.set(USER_REDIS_SESSION+":"+user.getId(), uniqueToken,1000*60*30);
//
// UsersVO userVo=new UsersVO();
// //拷贝对象
// BeanUtils.copyProperties(user, userVo);
// userVo.setUserToken(uniqueToken);
UsersVO userVo=setUserRedisSessionToKen(user);
return IMoocJSONResult.ok(userVo);
}
public UsersVO setUserRedisSessionToKen(Users userModel) {
String uniqueToken =UUID.randomUUID().toString();
redis.set(USER_REDIS_SESSION+":"+userModel.getId(), uniqueToken,1000*60*30);
UsersVO userVo=new UsersVO();
//拷贝对象
BeanUtils.copyProperties(userModel, userVo);
userVo.setUserToken(uniqueToken);
return userVo;
}
@ApiOperation(value="用户登录" ,notes="用户登录接口")
@PostMapping("/login")
public IMoocJSONResult login(@RequestBody Users user) throws Exception{
String username=user.getUsername();
String password=user.getPassword();
//1.判断密码是否为空
if(StringUtils.isBlank(username)||StringUtils.isBlank(password)) {
return IMoocJSONResult.errorMsg("用户密码不能为空");
}
//2.判断用户是否存在
Users userResult=userService.queryUserForLogin(username,MD5Utils.getMD5Str(password));
if(userResult!=null) {
userResult.setPassword("");
UsersVO userVo=setUserRedisSessionToKen(userResult);
return IMoocJSONResult.ok(userVo);
}else {
return IMoocJSONResult.errorMsg("用户或者密码不正确,请重试");
}
}
@ApiOperation(value="用户注销" ,notes="用户注销接口")
@ApiImplicitParam(name="userId" ,value="用户id",required=true,
dataType="String",paramType="query")
@PostMapping("/logout")
public IMoocJSONResult login(String userId) throws Exception{
redis.del(USER_REDIS_SESSION+":"+userId);
return IMoocJSONResult.ok("用户或者密码不正确,请重试");
}
}
@Api 注解可以用来标记 Controller 的功能
@ApiOperation 注解用来标记一个方法的作用
@ApilmplicitParam 注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入
@ApilmplicitParams 如果有多个参数,则需要使用多个 @ApilmplicitParam 注解来描述, 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中
@ApiModel 如果参数是一个对象,则需要在对象所在的类上加上此注解
@ApiModelProperty 如果参数是一个对象,则需要在对应的属性上加上此注解,还需要在对象所在的类上加上 @ApiModel
@ApiIgnore 注解标识此参数可以忽略
package com.imooc.pojo;
import javax.persistence.*;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel(value="用户对象",description="这是用户对象")
public class Users {
@ApiModelProperty(hidden=true)
@Id
private String id;
/**
* 用户名
*/
@ApiModelProperty(value="用户名字",name="username",example="imoocuser",required=true)
private String username;
/**
* 密码
*/
@ApiModelProperty(value="密码",name="password",example="132456",required=true)
private String password;
/**
* 我的头像,如果没有默认给一张
*/
@ApiModelProperty(hidden=true)
@Column(name = "face_image")
private String faceImage;
/**
* 昵称
*/
private String nickname;
/**
* 我的粉丝数量
*/
@ApiModelProperty(hidden=true)
@Column(name = "fans_counts")
private Integer fansCounts;
/**
* 我关注的人总数
*/
@ApiModelProperty(hidden=true)
@Column(name = "follow_counts")
private Integer followCounts;
/**
* 我接受到的赞美/收藏 的数量
*/
@ApiModelProperty(hidden=true)
@Column(name = "receive_like_counts")
private Integer receiveLikeCounts;
/**
* @return id
*/
public String getId() {
return id;
}
/**
* @param id
*/
public void setId(String id) {
this.id = id;
}
/**
* 获取用户名
*
* @return username - 用户名
*/
public String getUsername() {
return username;
}
/**
* 设置用户名
*
* @param username 用户名
*/
public void setUsername(String username) {
this.username = username;
}
/**
* 获取密码
*
* @return password - 密码
*/
public String getPassword() {
return password;
}
/**
* 设置密码
*
* @param password 密码
*/
public void setPassword(String password) {
this.password = password;
}
/**
* 获取我的头像,如果没有默认给一张
*
* @return face_image - 我的头像,如果没有默认给一张
*/
public String getFaceImage() {
return faceImage;
}
/**
* 设置我的头像,如果没有默认给一张
*
* @param faceImage 我的头像,如果没有默认给一张
*/
public void setFaceImage(String faceImage) {
this.faceImage = faceImage;
}
/**
* 获取昵称
*
* @return nickname - 昵称
*/
public String getNickname() {
return nickname;
}
/**
* 设置昵称
*
* @param nickname 昵称
*/
public void setNickname(String nickname) {
this.nickname = nickname;
}
/**
* 获取我的粉丝数量
*
* @return fans_counts - 我的粉丝数量
*/
public Integer getFansCounts() {
return fansCounts;
}
/**
* 设置我的粉丝数量
*
* @param fansCounts 我的粉丝数量
*/
public void setFansCounts(Integer fansCounts) {
this.fansCounts = fansCounts;
}
/**
* 获取我关注的人总数
*
* @return follow_counts - 我关注的人总数
*/
public Integer getFollowCounts() {
return followCounts;
}
/**
* 设置我关注的人总数
*
* @param followCounts 我关注的人总数
*/
public void setFollowCounts(Integer followCounts) {
this.followCounts = followCounts;
}
/**
* 获取我接受到的赞美/收藏 的数量
*
* @return receive_like_counts - 我接受到的赞美/收藏 的数量
*/
public Integer getReceiveLikeCounts() {
return receiveLikeCounts;
}
/**
* 设置我接受到的赞美/收藏 的数量
*
* @param receiveLikeCounts 我接受到的赞美/收藏 的数量
*/
public void setReceiveLikeCounts(Integer receiveLikeCounts) {
this.receiveLikeCounts = receiveLikeCounts;
}
}
4.启动 SpringBoot 应用
SpringBoot 启动成功后,访问 http://localhost:8081/swagger-ui.html
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
//作用为:配置spring容器(应用上下文)
@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
//配置资源映射访问所有资源(/**)
registry.addResourceHandler("/**")
.addResourceLocations("classpath:/META-INF/resources/")
}
}
1、静态资源路径是指系统可以直接访问的路径,且路径下的所有文件均可被用户通过浏览器直接读取。
2、在Springboot中默认的静态资源路径有:classpath:/META-INF/resources/,classpath:/resources/,classpath:/static/,classpath:/public/