SpringBoot整合Swagger2
随着前后端分离的日益盛行,接口已经是开发过程中不可避免的了,而一个好的接口文档对于开发进度与协同起到了举足轻重的作用,下面介绍下swagger2这个接口文档工具。
首先是创建一个Spring Boot项目,加入web依赖,创建成功后,加入两个Swagger2相关的依赖,完整的依赖如下:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
Swagger2的配置也是比较容易的,在项目创建成功之后,只需要开发者自己提供一个Docket的Bean即可,如下:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.basePackage("com.cp.swagger.controller"))
.paths(PathSelectors.any())
.build().apiInfo(new ApiInfoBuilder()
.title("springboot整合Swagger")
.description("springboot整合swagger,详细信息。。。")
.version("9.0")
.contact(new Contact("cptm","http://www.gcp168.cn","123@163.com"))
.license("The Apache License")
.licenseUrl("http://www.baidu.com")
.build());
}
}
这里提供一个配置类,首先通过@EnableSwagger2注解启用Swagger2,然后配置一个Docket Bean,这个Bean中,配置映射路径和要扫描的接口的位置,在apiInfo中,主要配置一下Swagger2文档网站的信息,例如网站的title,网站的描述,联系人的信息,使用的协议等等。
如此,Swagger2就算配置成功了,非常方便。
此时启动项目,输入http://localhost:8080/swagger-ui.html,能够看到如下页面,说明已经配置成功了:
接下来就是创建接口了,Swagger2相关的注解其实并不多,而且很容易懂,下面我来分别举例说明:
@RestController
@Api(tags = "用户管理接口")
@RequestMapping("/user")
public class UserController {
@ApiOperation("根据id查询用户")
@ApiImplicitParam(name = "id", value = "用户id", defaultValue = "99")
@GetMapping("/")
public User getUserById(Long id) {
User user = new User();
user.setId(id);
return user;
}
@ApiOperation("根据id更新用户名")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户id", defaultValue = "99"),
@ApiImplicitParam(name = "username", value = "用户名", defaultValue = "javaboy")
})
@PutMapping("/")
public User updateUsernameById(String username, Long id) {
User user = new User();
user.setId(id);
user.setUsername(username);
return user;
}
@PostMapping("/")
@ApiOperation("添加用户")
public User addUser(@RequestBody User user) {
return user;
}
@DeleteMapping("/{id}")
@ApiOperation("根据id 删除用户")
public void deleteUserById(@PathVariable Long id) {
}
@GetMapping("/hello")
public String hello(String name) {
return "hello " + name + " !";
}
}
1.@Api注解可以用来标记当前Controller的功能。
2.@ApiOperation注解用来标记一个方法的作用。
3.@ApiImplicitParam注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入。
4.如果有多个参数,则需要使用多个@ApiImplicitParam注解来描述,多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
5.需要注意的是,@ApiImplicitParam注解中虽然可以指定参数是必填的,但是却不能代替@RequestParam(required = true),前者的必填只是在Swagger2框架内必填,抛弃了Swagger2,这个限制就没用了,所以假如开发者需要指定一个参数必填,@RequestParam(required = true)注解还是不能省略。
6.如果参数是一个对象(例如上文的更新接口),对于参数的描述也可以放在实体类中。例如下面一段代码
@ApiModel
public class User {
@ApiModelProperty(value = "用户id")
private Integer id;
@ApiModelProperty(value = "用户名")
private String username;
@ApiModelProperty(value = "用户地址")
private String address;
//getter/setter
}
好了,经过如上配置之后,接下来,刷新刚刚打开的页面,可以看到如下效果:
可以看到,所有的接口这里都列出来了,包括接口请求方式,接口地址以及接口的名字等,点开一个接口,可以看到如下信息:
可以看到,接口的参数,参数要求,参数默认值等等统统都展示出来了,参数类型下的query表示参数以key/value的形式传递,点击右上角的Try it out,就可以进行接口测试:
点击Execute按钮,表示发送请求进行测试。测试结果会展示在下面的Response中。
当然,除了这些之外,还有一些响应值的注解,都比较简单,可以自己摸索下。
之前我们一直在学习springsecurity,如果我们的Spring Boot项目中集成了Spring Security,那么如果不做额外配置,Swagger2文档可能会被拦截,此时只需要在Spring Security的配置类中重写configure方法,添加如下过滤即可:
@Override
public void configure(WebSecurity web) throws Exception {
web.ignoring()
.antMatchers("/swagger-ui.html")
.antMatchers("/v2/**")
.antMatchers("/swagger-resources/**");
}
如此之后,Swagger2文件就不需要认证就能访问了。不知道大家有没有看懂呢?有问题欢迎留言讨论。