SpringBoot整合Swagger3.0与常用注解
Swagger3.0
- 一.整合SpringBoot
- 二.Swagger常用注解说明
-
- 2.1 控制类中的注解
- 2.2 返回实体类和参数实体类注解
- 三.Swagger-Ui插件
一.整合SpringBoot
SpringBoot整合Swagger3.0有很多需要注意的细节,一直在出问题,借鉴了很多人的,特此记录。
访问路径：http://localhost:8080/swagger-ui/index.html
Swagger3.0依赖导入(这个依赖可以代替另外两个，更好的与SpringBoot整合)
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-boot-starterartifactId>
<version>3.0.0version>
dependency>
接下来就是需要配置Swagger
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/*Docket封装接口文档信息*/
@Bean
public Docket getDocket(){
ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
apiInfoBuilder.title("<<互联商城>>后端接口说明")
.description("此文档详细说明了后端接口规范")
.version("v 1.0.0")
.contact(new Contact("Mordle","https://blog.csdn.net/fhuqw?spm=1010.2135.3001.5343","[email protected]"));
ApiInfo info = apiInfoBuilder.build();
Docket docket = new Docket(DocumentationType.SWAGGER_2)//指定文档风格
.apiInfo(info)//指定生成文档中的封面信息，文档的标题、作者、版本
.select()
.apis(RequestHandlerSelectors.basePackage("com.mordle.mall.controller"))
.paths(PathSelectors.any())
.build();
return docket;
}
}
启动项会报空指针异常
错误原因：SpringBoot2.6.x使用PathPatternMatcher匹配路径，Swagger引用的Springfox基于AntPathMatcher匹配路径。匹配方式不同，导致错误。
解决思路：将SpringBoot的匹配路径方式更改为AntPathMatcher，两者相同即可。添加配置信息如下：
注意：配置文件可以写成.properties或者.yaml，但不能是.yml(不知道为啥)
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
此时访问会报404找不到页面，原因是mvc拦截，需要另外配置
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
/**
* 添加静态资源处理器
* @param registry
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/swagger-ui/**").addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/").resourceChain(false);
}
/**
* 添加视图控制器
* @param registry
*/
@Override
public void addViewControllers(ViewControllerRegistry registry) {
registry.addViewController("/swagger-ui/").setViewName("/swagger-ui/index.html");
}
}
二.Swagger常用注解说明
2.1 控制类中的注解
@Api 类注解,在控制类添加此注解,可以对控制器类进行功能说明
@ApiOperation 方法注解：说明接口方法的作用
@ApiImplicitParams和@ApiImplicitParam 方法注解,说明接口方法的参数
@ApiIgnore 方法注解,接口不会在ui文档中出现
@RestController
@RequestMapping("/user")
@Api(value = "提供用户的登录和注册接口",tags = "用户管理")
public class UserController {
@Resource
private UserService userService;
@ApiOperation("用户登录接口")
@ApiImplicitParams({
@ApiImplicitParam(dataType = "string",name = "username",value = "用户登录账号",required = true),
@ApiImplicitParam(dataType = "string",name = "password",value = "用户登录密码",required = false,defaultValue = "111111")
})
@GetMapping("/login")
public ResultVO login(@RequestParam("username") String name,@RequestParam(value = "password",defaultValue = "111111") String pwd){
return userService.checkLogin(name,pwd);
}
}
2.2 返回实体类和参数实体类注解
@ApiModel 类注解,在返回和参数实体类添加此注解,可以对返回和参数实体类进行说明
@ApiModelProperty 参数注解
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "响应的VO对象",description = "封装接口返回给前端的数据")
public class ResultVO {
//响应给前端的状态码
@ApiModelProperty(value = "响应状态码",dataType = "int")
private int code;
//响应给前端的信息
@ApiModelProperty(value = "响应信息",dataType = "String")
private String msg;
//响应给前端的数据
@ApiModelProperty(value = "响应数据",dataType = "Object")
private Object data;
}
@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "User对象",description = "用户/买家信息")
public class User {
@ApiModelProperty(dataType ="int",required = false,value = "用户id")
private String id;
@ApiModelProperty(dataType = "String",required = true,value = "用户注册账号")
private String name;
@ApiModelProperty(dataType = "String",required = true,value = "用户注册密码")
private String pwd;
}
三.Swagger-Ui插件
访问地址：http://localhost:8080/doc.html
导入依赖
<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>