Spring Boot整合Swagger 2
1. Swagger 2简介
在前后端分离开发中,为了减少与其他团队的沟通成本,-般构建一份RESTful API文档来描述所有的接口信息,但是这种做法有很大的弊端,分别说明如下:
- 接口众多,编写RESTful API文档工作量巨大,因为RESTful API文档不仅要包含接口的基本信息,如接口地址、接口请求参数以及接口返回值等,还要包含HTTP请求类型、HTTP请求头、请求参数类型、返回值类型、所需权限等。
- 维护不方便, 一旦接口发生变化,就要修改文档。
- 接口测试不方便, 一般只能借助第三方工具(如Postman)来测试。
Swagger2是一个开源软件框架,可以帮助开发人员设计、构建、记录和使用RESTful Web服务,它将代码和文档融为一-体,可以完美解决上面描述的问题,使开发人员将大部分精力集中到业务中,而不是繁杂琐碎的文档中。
Swagger2可以非常轻松地整合到Spring Boot项目中,下 面来看如何整合。
2. 整合Spring Boot
首先创建Spring Boot Web项目,添加Swagger 2相关依赖,代码如下:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.22</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.22</version>
</dependency>
注意:因为我这里引入的 swagger ui 是 2.7 以上的版本,所以还需要引入 guava,否则会因为 guava 兼容性问题造成项目启动报错(无法启动)。SpringBoot 版本 2.2.6.RELEASE,版本不能高与这个版本,否则 Swagger 版本不匹配报错。
接下来创建Swagger 2的配置类,代码如下:
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//是否开启 (true 开启 false隐藏。生产环境建议隐藏)
//.enable(false)
.select()
//扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
.apis(RequestHandlerSelectors.basePackage("suohechuan.testforever"))
//指定路径处理PathSelectors.any()代表所有的路径
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//设置文档标题(API名称)
.title("SpringBoot中使用Swagger2接口规范")
//文档描述
.description("接口说明")
//服务条款URL
.termsOfServiceUrl("http://localhost:8080/")
//版本号
.version("1.0.0")
.build();
}
}
代码解释:
-
通过apis方法配置要扫描的controller位置,通过paths方法配置路径。
-
在apiInfo中构建文档的基本信息,例如描述、联系人信息、版本、标题等。
使用@EnableOpenApi注解,启用swagger配置
@EnableOpenApi
@SpringBootApplication
public class TestforeverApplication {
public static void main(String[] args) {
SpringApplication.run(TestforeverApplication.class, args);
}
}
Swagger 2配置完成后,接下来就可以开发接口了,代码如下:
@RestController
@Api(tags = "用户数据接口")
public class UserController {
@ApiOperation(value = "查询用户", notes = "根据 id 查询用户")
@ApiImplicitParam(paramType = "path", name = "id", value = "用户 id", required = true)
@GetMapping("/user/{id}")
public String getUserById(@PathVariable Integer id) {
return "查找的用户id是:" + id;
}
@ApiOperation(value = "新增用户", notes = "根据传入的用户名和密码添加一个新用户")
@ApiImplicitParams({
@ApiImplicitParam(paramType = "query", name = "username",
value = "用户名", required = true, defaultValue = "test"),
@ApiImplicitParam(paramType = "query", name = "password",
value = "密码", required = true, defaultValue = "123")
})
@PostMapping("/user")
public String addUser(@RequestParam String username, @RequestParam String password) {
return "新增用户:" + username + " " + password;
}
@ApiOperation(value = "删除用户", notes = "根据 id 删除用户")
@ApiResponses({
@ApiResponse(code = 200, message = "删除成功!"),
@ApiResponse(code = 500, message = "删除失败!")
})
@DeleteMapping("/user/{id}")
public Integer deleteUserById(@PathVariable Integer id) {
return id;
}
@ApiOperation(value = "修改用户", notes = "传入用户信息进行更新修改")
@PutMapping("/user")
public String updateUser(@RequestBody User user) {
return user.toString();
}
@ApiIgnore
@GetMapping("/user/test")
public String test() {
return "这是一个测试接口,不需要在api文档中显示。";
}
}
代码解释:
- @Api注解用在类上,用来描述整个Controller信息。
- @ApiOperation 注解用在开发方法上,用来描述一个方法的基本信息,value 是对方法作用的一个简短描述,notes则用来备注该方法的详细作用。
- @ApiImplicitParam注解用在方法上,用来描述方法的参数, paramType是指方法参数的类型,可选值有path (参数获取方式@PathVariable )、query (参数获取方式@RequestParam ). header(参数获取方式@RequestHeader)、body 以及form; name 表示参数名称,和参数变量对应;value是参数的描述信息; required 表示该字段是否必填; defaultValue 表示该字段的默认值。注意,这里的required和defaultValue等字段只是文档上的约束描述,并不能真正约束接口,约束接口还需要在@RequestParam中添加相关属性。
如果方法有多个参数,可以将多个参数的@ApilmplicitParam注解放到@ApiImplicitParams中。 - @ApiResponse 注解是对响应结果的描述,code 表示响应码,message 表示相应的描述信息,若有多个@ApiResponse,则放在一个@ApiResponses中。
- 在 updateUser方法中,使用@RequestBody注解来接收数据,此时可以通过@ApiModel注解和@ApiModelProperty注解配置User对象的描述信息。
- @ApiIgnore 注解表示不对某个接口生成文档。
(1)@Api 注解标注在类上用来描述整个 Controller 信息。
(2)@ApiOperation 注解标注在方法上,用来描述一个方法的基本信息。
(3)@ApiImplicitParam 注解标注在方法上,用来描述方法的参数。其中 paramType 是指方法参数的类型,有如下可选值:
path:参数获取方式为 @PathVariable
query:参数获取方式为 @RequestParam
header:参数获取方式为 @RequestHeader
body
form
(4)如果有多个参数,可以将多个参数的 @ApiImplicitParam 注解放到 @ApiImplicitParams 中。
(5)@ApiResponse 是对响应结果的描述。code 表示响应码,message 为相应的描述信息。如果有多个 @ApiResponse,则放在一个 @ApiResponses 中。
(6)@ApiIgnore 注解表示不对某个接口生成文档。
接下来启动Spring Boot 项目,在浏览器中输入启动 Spring Boot 项目,在浏览器中输入 http://localhost:8080/swagger-ui/index.html 即可看到接口文档。即可看到接口文档,如图所示。