SpringBoot整合Swagger2
引入Swagger2依赖
<!-- swagger2 配置 -->
<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>
编写Swagger配置类
package com.imooc.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2 {
// http://localhost:8088/swagger-ui.html 原路径
// http://localhost:8088/doc.html 原路径
// 配置swagger2核心配置 docket
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2) // 指定api类型为swagger2
.apiInfo(apiInfo()) // 用于定义api文档汇总信息
.select()
.apis(RequestHandlerSelectors
.basePackage("com.imooc.controller")) // 指定controller包
.paths(PathSelectors.any()) // 所有controller
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("天天吃货 电商平台接口api") // 文档页标题
.contact(new Contact("imooc",
"https://www.imooc.com",
"abc@imooc.com")) // 联系人信息
.description("专为天天吃货提供的api文档") // 详细信息
.version("1.0.1") // 文档版本号
.termsOfServiceUrl("https://www.imooc.com") // 网站地址
.build();
}
}
Controller相关配置
以用户登录、注册、登出为例
package com.imooc.controller;
import com.imooc.pojo.Users;
import com.imooc.pojo.bo.UserBO;
import com.imooc.service.StuService;
import com.imooc.service.UserService;
import com.imooc.utils.CookieUtils;
import com.imooc.utils.IMOOCJSONResult;
import com.imooc.utils.JsonUtils;
import com.imooc.utils.MD5Utils;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
@Api(value = "注册登录", tags = {"用于注册登录的相关接口"})
@RestController
@RequestMapping("passport")
public class PassportController {
@Autowired
private UserService userService;
@ApiOperation(value = "用户名是否存在", notes = "用户名是否存在", httpMethod = "GET")
@GetMapping("/usernameIsExist")
public IMOOCJSONResult usernameIsExist(@RequestParam String username) {
// 1. 判断用户名不能为空
if (StringUtils.isBlank(username)) {
return IMOOCJSONResult.errorMsg("用户名不能为空");
}
// 2. 查找注册的用户名是否存在
boolean isExist = userService.queryUsernameIsExist(username);
if (isExist) {
return IMOOCJSONResult.errorMsg("用户名已经存在");
}
// 3. 请求成功，用户名没有重复
return IMOOCJSONResult.ok();
}
@ApiOperation(value = "用户注册", notes = "用户注册", httpMethod = "POST")
@PostMapping("/regist")
public IMOOCJSONResult regist(@RequestBody UserBO userBO,
HttpServletRequest request,
HttpServletResponse response) {
String username = userBO.getUsername();
String password = userBO.getPassword();
String confirmPwd = userBO.getConfirmPassword();
// 0. 判断用户名和密码必须不为空
if (StringUtils.isBlank(username) ||
StringUtils.isBlank(password) ||
StringUtils.isBlank(confirmPwd)) {
return IMOOCJSONResult.errorMsg("用户名或密码不能为空");
}
// 1. 查询用户名是否存在
boolean isExist = userService.queryUsernameIsExist(username);
if (isExist) {
return IMOOCJSONResult.errorMsg("用户名已经存在");
}
// 2. 密码长度不能少于6位
if (password.length() < 6) {
return IMOOCJSONResult.errorMsg("密码长度不能少于6");
}
// 3. 判断两次密码是否一致
if (!password.equals(confirmPwd)) {
return IMOOCJSONResult.errorMsg("两次密码输入不一致");
}
// 4. 实现注册
Users userResult = userService.createUser(userBO);
userResult = setNullProperty(userResult);
CookieUtils.setCookie(request, response, "user",
JsonUtils.objectToJson(userResult), true);
// TODO 生成用户token，存入redis会话
// TODO 同步购物车数据
return IMOOCJSONResult.ok();
}
@ApiOperation(value = "用户登录", notes = "用户登录", httpMethod = "POST")
@PostMapping("/login")
public IMOOCJSONResult login(@RequestBody UserBO userBO,
HttpServletRequest request,
HttpServletResponse response) throws Exception {
String username = userBO.getUsername();
String password = userBO.getPassword();
// 0. 判断用户名和密码必须不为空
if (StringUtils.isBlank(username) ||
StringUtils.isBlank(password)) {
return IMOOCJSONResult.errorMsg("用户名或密码不能为空");
}
// 1. 实现登录
Users userResult = userService.queryUserForLogin(username,
MD5Utils.getMD5Str(password));
if (userResult == null) {
return IMOOCJSONResult.errorMsg("用户名或密码不正确");
}
userResult = setNullProperty(userResult);
CookieUtils.setCookie(request, response, "user",
JsonUtils.objectToJson(userResult), true);
// TODO 生成用户token，存入redis会话
// TODO 同步购物车数据
return IMOOCJSONResult.ok(userResult);
}
private Users setNullProperty(Users userResult) {
userResult.setPassword(null);
userResult.setMobile(null);
userResult.setEmail(null);
userResult.setCreatedTime(null);
userResult.setUpdatedTime(null);
userResult.setBirthday(null);
return userResult;
}
@ApiOperation(value = "用户退出登录", notes = "用户退出登录", httpMethod = "POST")
@PostMapping("/logout")
public IMOOCJSONResult logout(@RequestParam String userId,
HttpServletRequest request,
HttpServletResponse response) {
// 清除用户的相关信息的cookie
CookieUtils.deleteCookie(request, response, "user");
// TODO 用户退出登录，需要清空购物车
// TODO 分布式会话中需要清除用户数据
return IMOOCJSONResult.ok();
}
}
实现效果 http://localhost:8088/swagger-ui.html
写在最后
Github上有对swagger2界面进行优化的Bootstrap插件
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.6</version>
</dependency>
访问地址:http://localhost:8088/doc.html
