swagger2简介
以前我们写接口的时候,都需要生成对应的接口文档给前端,每次修改接口时,对应文档也要跟着修改,这就有可能导致文档更新不及时、文档编写麻烦等问题。
swagger2出现就是为了解决以上问题,Swagger2可以轻松的整合到Spring Boot中,并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。
springboot整合swagger2
1、添加swagger2依赖
<properties>
<swagger.version>2.9.2</swagger.version>
</properties>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
2、创建swagger配置类
@Configuration
@EnableSwagger2
public class SwaggerConfig {
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("API接口文档")
.description("用户信息管理")
.version("1.0.0")
.build();
}
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.spring.providerone.controller"))//这里写的是API接口所在的包位置
.paths(PathSelectors.any())
.build();
}
}
如上代码所示,通过@Configuration注解,让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。再通过createRestApi函数创建Docket的Bean之后,apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,本例采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容(除了被@ApiIgnore指定的请求)。
3、修改controller类
@Api(tags ="用户信息管理")
@RestController
public class UserController {
@Autowired
private IUserServiceservice;
@ApiOperation(value ="查询所有用户信息")
@PostMapping("/user/userList")
public List getUserList(){
return service.findAllUser();
}
@ApiOperation(value ="新增用户信息")
@PostMapping("/user/add")
public String addUser(@RequestBody User user){
if(user!=null){
service.createUser(user);
return "success";
}else{
return "error";
}
}
@ApiOperation(value ="删除用户信息")
@PostMapping("/user/delUser")
public String delUser(@RequestParam String id){
try {
service.delUser(id);
return "del success";
}catch (Exception e ){
e.printStackTrace();
return "del false";
}
}
@ApiOperation(value ="修改用户信息")
@PostMapping("/user/updateUser")
public String updateUser(@RequestBody User user){
try {
service.updateUser(user);
return "update success";
}catch (Exception e ){
e.printStackTrace();
return "update false";
}
}
//测试方法,返回服务器端口,以判断是访问哪个服务
@Value("${server.port}")
Stringport;
@ApiOperation(value ="测试负载均衡")
@PostMapping("/user/hi")
public String home(@RequestParam(value ="name", defaultValue ="zhangsan") String name) {
return "hi " + name +" ,i am from port:" +port;
}
}
@Api 用在类上,说明该类的作用
@ApiOperation:用在方法上,说明方法的作用,每一个url资源的定义
@PostMapping("/user/…")是以post请求,本次使用post请求
@GetMapping("/user/…")是以get请求
@RequestMapping("/user/…")会显示所有的请求:GET,HEAD,POST.PUT,DELETE,OPTIONS,PATCH
4、启动springboot项目,在页面中访问:http://localhost:8002/swagger-ui.html#/,就可
5、API文档访问与测试
点击用户信息管理,可以看到后台提供的接口,再点击接口信息,就会出现以下界面,我们要调试的话可以点击Try id out按钮
输入用户信息,点击Execute,就可以测试了