Swagger
一、为什么要使用swagger
在前后端分离的时代,前端人员和后端人员无法做到“及时协商,尽早解决”,最终会导致许多的问题出现。
解决方案:
- 首先制定一个schema,实时更新最新的API,降低集成的风险;
- 前后端分离
- 前端测试后端接口:postman
- 后端提供接口,需要实时更新最新的消息及改动
这里可以参考swagger的官网 https://swagger.io/
二、springboot集成swagger
这里是以springboot 2.6.0和swagger3.0.0版本作为演示
首先在pom.xml文档里面加入这个依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
然后需要写一个对于swagger的配置类
@Configuration
@EnableOpenApi
@EnableWebMvc
public class SwaggerConfig {
//分组
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(true)//默认为true 关闭后,则不能使用swagger
.select()
//指定接口的位置
.apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
//过滤什么路径
//.paths()
.build();
//.globalOperationParameters(pars);
}
private ApiInfo apiInfo() {
//作者信息
Contact contact = new Contact("William","https://mercurys-52hz.gitee.io/","chening_william@163.com");
return new ApiInfo(
"William的接口文档",
"前端根据接口进行测试",
"1.0",
"https://mercurys-52hz.gitee.io/",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}
三、配置详解
1.swagger配置
在swagger3.0.0版本中,需要在配置类的上面加上 @EnableOpenApi,当然还有配置类需要的@Configuration注解,最重要的就是一定需要加上 @EnableWebMvc注解,不然控制面板就会报错,就是这个错误浪费了我一下午的时间
可以通过设置 .apis(RequestHandlerSelectors.basePackage(“com.swagger.controller”)) 里面的参数用来指定需要扫描的包,这里面还可以设置更多的参数,详情可以参照上面的这张图片。加上 paths() 后可以在里面设置过滤的路径不扫描。
2.信息配置
private ApiInfo apiInfo() {
//作者信息
Contact contact = new Contact("William","https://mercurys-52hz.gitee.io/","chening_william@163.com");
return new ApiInfo(
"William的接口文档",
"前端根据接口进行测试",
"1.0",
"https://mercurys-52hz.gitee.io/",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList()
);
}
}
这里主要就是配置一些作者的信息的名字好联系啥的,不太重要,就不细讲了。
3.配置多api分组
//分组
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}
作用就是为每个api分一下组。作用效果如下图
4.通过注解配置注释
凭空传过去,前端一定会一脸懵逼的,这时候就需要注释来帮助理解了。
四、swagger的使用
注释的使用
Swagger使用的注解及其说明:
@Api:用在类上,说明该类的作用。
@ApiOperation:注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam:用来注解来给方法入参增加说明。
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
@ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:描述一个model的属性
paramType:指定参数放在哪个地方 | header:请求参数放置于Request Header,使用@RequestHeader获取 query:请求参数放置于请求地址,使用@RequestParam获取 path:(用于restful接口)–>请求参数的获取:@PathVariable body:(不常用) form(不常用 |
---|---|
name:参数名 | |
dataType:参数类型 | |
required:参数是否必须传 | true / false |
value:说明参数的意思 | |
defaultValue:参数的默认值 |
示例:
@RestController
@Api("登录控制器")
public class loginController {
@Autowired
private UserService userService;
@RequestMapping("/login")
@ApiOperation("输入用户的id和密码,查询用户信息,如果数据库没有或者密码不对应则会返回空值")
@ApiImplicitParams({ @ApiImplicitParam(paramType = "query",name = "id",value = "用户的id",required = true,dataType = "Integer",dataTypeClass = Integer.class,example = "123"),
@ApiImplicitParam(paramType = "query",name = "password", value = "密码",required = true,dataType = "String",dataTypeClass = String.class)
})
public User login(@RequestParam("id")int id, @RequestParam("password") String password){
User loginuser = userService.doLogin(id,password);
if(loginuser == null){
return null;
}else{
return loginuser;
}
}
}
这里补充一点,在使用swagger(version 3.0)的进行上传文件的调试的时候需要注意一点,记得把把参数那里的文件的注解换一下,才能使swagger显示出来上传文件的按钮
@RequestPart("file") MultipartFile file
引一下流,我的博客网站链接: mercury.