1、导入pom.xml
<!-- 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>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.6</version>
</dependency>
2、编写Swagger2.java配置文件,内容根据注释自行修改(新建路径可自定,我这里是在src/main/java/com/xpf/config/Swagger2.java)
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 //开启swagger2
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.xpf.controller")) // 指定controller包
.paths(PathSelectors.any()) // 所有controller
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("天天吃货 电商平台接口api") // 文档页标题
.contact(new Contact("xpf",
"https://www.baidu.com",
"xiepfa@yonyou.com")) // 联系人信息
.description("专为天天吃货提供的api文档") // 详细信息
.version("1.0.1") // 文档版本号
.termsOfServiceUrl("https://www.baidu.com") // 网站地址
.build();
}
}
3、访问地址(端口根据自身配置修改,一般8080)
官方路径:http://localhost:8088/swagger-ui.html 使用新ui路径(推荐):http://localhost:8088/doc.html
效果图:
4、扩展:swagger2的一些注释的使用
4.1 控制controller的
以下列举一些常用的注释,可自行测试
@ApiIgnore //swagger2忽略此controller
//用于左侧大标签
@Api(value = "注册登录", tags = {"用于注册登录的相关接口"})
//用于左侧大标签下的每个接口
@ApiOperation(value = "用户是否存在", notes = "用户是否存在1",httpMethod = "GET")
//示例代码
@Api(value = "注册登录", tags = {"用于注册登录的相关接口"})
@RestController //所有请求都是json对象
@RequestMapping("passport")
public class PassportController {
@Autowired
private UserService userService;
@ApiOperation(value = "用户是否存在", notes = "用户是否存在1",httpMethod = "GET")
@GetMapping("/usernameIsExist")
public JSONResult usernameIsExist(@RequestParam String username){
// 1.判断用户是否不能为空
if (StringUtils.isBlank(username)){
return JSONResult.errorMsg("用户名不能为空");
}
//2. 查找注册的用户是否存在
boolean isExist = userService.usernameIsExist(username);
if (isExist)
return JSONResult.errorMsg("用户名已存在");
//3. 请求成功,用户名没有重复
return JSONResult.ok();
}
}
4.2 控制具体参数的
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
//添加swagger2文档字段解释
@ApiModel(description = "从客户端,由用户传入的数据封装在此entity中")
public class UserBO {
@ApiModelProperty(value = "用户名",name = "username", example = "xpf", required = true)
private String username;
@ApiModelProperty(value = "密码",name = "password", example = "123123", required = true)
private String password;
@ApiModelProperty(value = "确认密码",name = "confirmPassword", example = "123123", required = true)
private String confirmPassword;
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
public String getConfirmPassword() {
return confirmPassword;
}
public void setConfirmPassword(String confirmPassword) {
this.confirmPassword = confirmPassword;
}
}