程序员最头疼的事是什么呢?我想一定是写接口文档,尤其是一大堆参数的那种。那么我们有没有办法改变这种情况呢?答案是肯定的。因此我们的主角 Swagger 登场了。
引入Swagger依赖包
创建springboot web 项目,引入以下依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
创建 Swagger 配置类并开启注解
这里有两点要注意的地方:
- 一定要开启
@EnableSwagger2
注解 - 配置正确的扫描路径
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;
/**
1. Created by pengq on 2019/9/3 9:20.
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//swagger 的扫描路径,这里指的是生成该路径下所以类的文档
.apis(RequestHandlerSelectors.basePackage("pengq.springboot.mybatisplus.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot2 集成 Swagger")
.description("swagger 学习总结")
.contact(new Contact("pengq","","pengq0717@qq.com"))
.version("1.0")
.build();
}
}
在Controller 中配置 Swagger 注解
- 首先需要在我们的controller类上打上
@Api
注解 - 编写方法体上的描述信息,这里列举了几种常见的Controller编写方式,如果不全面欢迎大家补充。
示例1:无参数的接口
@ApiOperation("查询所有用户")
@ApiResponses({
@ApiResponse(code = 200, message = "操作成功", response = Users.class),
@ApiResponse(code = 500, message = "服务器内部异常")
})
@GetMapping(value = "/v1/users/", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
public Object getAllUser() {
return userService.listUser();
}
示例2:有参数 用 @RequestBody
接收
@ApiOperation("用户注册")
@PostMapping(value = "/v1/users/register", consumes = MediaType.APPLICATION_JSON_UTF8_VALUE, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
public Object register(@RequestBody Users users) {
return userService.register(users);
}
示例3:参数 用 @PathVariable
接收
@ApiOperation("查询用户详情")
@ApiImplicitParam(paramType = "path", name = "id")
@GetMapping(value = "/v1/users/{id}", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
public Object getUserInfo(@PathVariable("id") Integer id) {
return userService.getUserById(id);
}
示例4:多参数 用 @RequestParam
接收
@ApiOperation("用户登录")
@ApiImplicitParams({
@ApiImplicitParam(paramType = "query", dataType = "String", name = "username", value = "登录名",required = true),
@ApiImplicitParam(paramType = "query", dataType = "String", name = "password", value = "登录密码",required = true)
})
@PostMapping(value = "/v1/users/login", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
public Object login(@RequestParam(name = "username") String username,
@RequestParam(name = "password") String password) {
return userService.login(username, password);
}
示例5:参数 用 @RequestHeader
接收
@ApiOperation("header 测试")
@ApiImplicitParam(paramType = "header", dataType = "String", name = "token", value = "token")
@PostMapping(value = "/v1/users/check", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
public Object check(@RequestHeader("token") String token) {
return token;
}
好,到此我们的swagger配置已经完成了,启动我们的项目,感受一下他的强大吧
访问url: http://localhost:8080/swagger-ui.html
这个就是swagger的web界面,该url的访问规则为 http://ip:端口号/swagger-ui.html
Swagger 常用注解总结
注解 | 属性 | 值 | 使用方式 | 描述 |
---|---|---|---|---|
@Api | @Api(value = "xx", tags = "xx",hidden = false) | |||
value | 字符串 | url的路径值 | ||
tags | 字符串 | 对controller的描述,如果设置这个值、value的值会被覆盖 | ||
hidden | boolean | 如果设置为true,该文档将会被隐藏 | ||
@ApiOperation | @ApiOperation("xxx") | |||
value | 字符串 | 用在方法头上,作为方法的描述 | ||
@ApiImplicitParams | @ApiImplicitParams({@ApiImplicitParam(xxx)}) | |||
数组 | @ApiImplicitParam | 用在方法头上,作为方法参数的描述 | ||
@ApiImplicitParam | @ApiImplicitParam(paramType = "query", dataType = "String", name = "xxx", value = "xxx") | |||
name | 字符串 | 与参数名对应 | ||
value | 字符串 | 参数名的描述 | ||
required | boolean | true/false 是否必须 | ||
dataType | 字符串 | 参数类型 | ||
paramType | 字符串 | 参数请求方式:query/path/header/body | ||
query | 对应@RequestParam 传递 | |||
path | 对应@PathVariable 传递 | |||
header | 对应@RequestHeader 传递 | |||
body | 不推荐使用,与 @RequestBody 标签一起会导致错误 | |||
defaultValue | 字符串 | 参数不传递时的默认值 | ||
@ApiResponses | @ApiResponses({@ApiResponse()}) | |||
数组 | @ApiResponse | 用在方法头上,作为方法返回值的描述 | ||
@ApiResponse | @ApiResponse(code = 200, message = "操作成功", response = Users.class) | |||
code | 整形 | 返回值编码 | ||
message | 字符串 | 返回值的描述信息 | ||
response | Class | 返回值类型 |
Swagger集成项目地址:Swagger集成项目地址