使用swagger来编写在线api文档

使⽤swagger来编写在线api⽂档
swagger是⼀个⾮常简单，强⼤的框架。

快速上⼿，只需要引⼊jar包，使⽤注解就可以⽣成⼀个漂亮的在线api⽂档pom.xml
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
View Code
写⼀个总的标题，对整个⽂档的描述
waggerConfig.java
package com.lzh;
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>();
("headerUserToken").description("userToken")
.modelRef(new ModelRef("string")).parameterType("header")
.required(false).build();
("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.lzh.controller"))
.paths(PathSelectors.any()).build()
.globalOperationParameters(pars);
}
/**
* @Description: 构建 api⽂档的信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 设置页⾯标题
.title("使⽤swagger2构建短视频后端api接⼝⽂档")
// 设置联系⼈
.contact(new Contact("敲代码的卡卡罗特", "", "imooc@"))
// 描述
.description("欢迎访问短视频接⼝⽂档，这⾥是描述信息")
// 定义版本号
.version("1.0").build();
}
}
View Code
然后在controller中写上需要注释的⽅法，⼀般需要这⼏种就可以满⾜我们了。

1.注释⽅法名字 @ApiOperation("上传⽂件")
2.注释⽅法中所需的参数的意思（参数是封装的对象，写在pojo的字段上） @ApiModelProperty("⽤户密码")
2.注释⽅法中所需的参数的意思（参数是普通的类型，写在⽅法的参数上） @ApiParam("⽂件file对象")
3.对接⼝类的描述 @Api(value="⽤户注册登录的接⼝", tags= {"注册和登录的controller"})
情景1：当⽅法的参数是⼀个对象的时候，⽐如登陆注册。

我们就需要在user对象中写注解。

package com.lzh.controller;
import ers;
import erService;
import com.lzh.utils.IMoocJSONResult;
import com.lzh.utils.MD5Utils;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiOperation;
import ng3.StringUtils;
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;
/**
* Created by 敲代码的卡卡罗特
* on 2018/11/2 12:37.
*/
@RestController
@Api(value="⽤户注册登录的接⼝", tags= {"注册和登录的controller"})
public class RegistLoginController {
@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 usernameIsExist = userService.queryUsernameIsExist(user.getUsername());
// 3. 保存⽤户，注册信息
if (!usernameIsExist) {
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("⽤户名已经存在，请换⼀个再试");
}
user.setPassword("");
// UsersVO userVO = setUserRedisSessionToken(user);
return IMoocJSONResult.ok(user);
}
}
View Code
对应的pojo
package com.lzh.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import javax.persistence.Column;
import javax.persistence.Id;
@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="123456", required=true)
private String password;
/**
* 我的头像，如果没有默认给⼀张
*/
@ApiModelProperty(hidden=true)
@Column(name = "face_image")
private String faceImage;
/**
* 昵称
*/
@ApiModelProperty(hidden=true)
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;
public Users() {
super();
}
public Users(String id, String username, String password, String faceImage, String nickname, Integer fansCounts, Integer followCounts, Integer receiveLikeCounts) {
super();
this.id = id;
ername = username;
this.password = password;
this.faceImage = faceImage;
this.nickname = nickname;
this.fansCounts = fansCounts;
this.followCounts = followCounts;
this.receiveLikeCounts = 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) {
ername = 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;
}
}
View Code
情景2：当参数是普通类型时，⽐如查询操作（1个参数时），我们可以在⽅法的上⾯写注解@ApiOperation(value="⽤户注销", notes="⽤户注销的接⼝")
@ApiImplicitParam(name="userId", value="⽤户id", required=true,
dataType="String", paramType="query")
@PostMapping("/logout")
public IMoocJSONResult logout(String userId) throws Exception {
redis.del(USER_REDIS_SESSION + ":" + userId);
return IMoocJSONResult.ok();
}
View Code
情景3：当参数是普通类型时，⽐如查询操作（多个参数时）
@ApiOperation(value="上传视频", notes="上传视频的接⼝")
@ApiImplicitParams({
@ApiImplicitParam(name="userId", value="⽤户id", required=true,
dataType="String", paramType="form"),
@ApiImplicitParam(name="bgmId", value="背景⾳乐id", required=false,
dataType="String", paramType="form"),
@ApiImplicitParam(name="videoSeconds", value="背景⾳乐播放长度", required=true,
dataType="String", paramType="form"),
@ApiImplicitParam(name="videoWidth", value="视频宽度", required=true,
dataType="String", paramType="form"),
@ApiImplicitParam(name="videoHeight", value="视频⾼度", required=true,
dataType="String", paramType="form"),
@ApiImplicitParam(name="desc", value="视频描述", required=false,
dataType="String", paramType="form")
})
@PostMapping(value="/upload", headers="content-type=multipart/form-data")
public IMoocJSONResult upload(String userId,
String bgmId, double videoSeconds,
int videoWidth, int videoHeight,
String desc,
@ApiParam(value="短视频", required=true)
MultipartFile file) throws Exception {
if (StringUtils.isBlank(userId)) {
return IMoocJSONResult.errorMsg("⽤户id不能为空...");
}
// ⽂件保存的命名空间
// String fileSpace = "C:/imooc_videos_dev";
// 保存到数据库中的相对路径
String uploadPathDB = "/" + userId + "/video";
String coverPathDB = "/" + userId + "/video";
FileOutputStream fileOutputStream = null;
InputStream inputStream = null;
// ⽂件上传的最终保存路径
String finalVideoPath = "";
try {
if (file != null) {
String fileName = file.getOriginalFilename();
// abc.mp4
String arrayFilenameItem[] = fileName.split("\\.");
String fileNamePrefix = "";
for (int i = 0 ; i < arrayFilenameItem.length-1 ; i ++) {
fileNamePrefix += arrayFilenameItem[i];
}
// fix bug: 解决⼩程序端OK，PC端不OK的bug，原因：PC端和⼩程序端对临时视频的命名不同// String fileNamePrefix = fileName.split("\\.")[0];
if (StringUtils.isNotBlank(fileName)) {
finalVideoPath = FILE_SPACE + uploadPathDB + "/" + fileName;
// 设置数据库保存的路径
uploadPathDB += ("/" + fileName);
coverPathDB = coverPathDB + "/" + fileNamePrefix + ".jpg";
File outFile = new File(finalVideoPath);
if (outFile.getParentFile() != null || !outFile.getParentFile().isDirectory()) {
// 创建⽗⽂件夹
outFile.getParentFile().mkdirs();
}
fileOutputStream = new FileOutputStream(outFile);
inputStream = file.getInputStream();
IOUtils.copy(inputStream, fileOutputStream);
}
} else {
return IMoocJSONResult.errorMsg("上传出错...");
}
} catch (Exception e) {
e.printStackTrace();
return IMoocJSONResult.errorMsg("上传出错...");
} finally {
if (fileOutputStream != null) {
fileOutputStream.flush();
fileOutputStream.close();
}
}
// 判断bgmId是否为空，如果不为空，
// 那就查询bgm的信息，并且合并视频，⽣产新的视频
if (StringUtils.isNotBlank(bgmId)) {
Bgm bgm = bgmService.queryBgmById(bgmId);
String mp3InputPath = FILE_SPACE + bgm.getPath();
MergeVideoMp3 tool = new MergeVideoMp3(FFMPEG_EXE);
String videoInputPath = finalVideoPath;
String videoOutputName = UUID.randomUUID().toString() + ".mp4";
uploadPathDB = "/" + userId + "/video" + "/" + videoOutputName;
finalVideoPath = FILE_SPACE + uploadPathDB;
tool.convertor(videoInputPath, mp3InputPath, videoSeconds, finalVideoPath); }
System.out.println("uploadPathDB=" + uploadPathDB);
System.out.println("finalVideoPath=" + finalVideoPath);
// 对视频进⾏截图
FetchVideoCover videoInfo = new FetchVideoCover(FFMPEG_EXE);
videoInfo.getCover(finalVideoPath, FILE_SPACE + coverPathDB);
// 保存视频信息到数据库
Videos video = new Videos();
video.setAudioId(bgmId);
video.setUserId(userId);
video.setVideoSeconds((float)videoSeconds);
video.setVideoHeight(videoHeight);
video.setVideoWidth(videoWidth);
video.setVideoDesc(desc);
video.setVideoPath(uploadPathDB);
video.setCoverPath(coverPathDB);
video.setStatus(VideoStatusEnum.SUCCESS.value);
video.setCreateTime(new Date());
String videoId = videoService.saveVideo(video);
return IMoocJSONResult.ok(videoId);
}
View Code。