SpringBoot整合Swagger
前后端分离后,后端写的接口要让前端人员能够看懂,而前端人员可能不能后端技术,所以我们需要写接口文档让他们能够看懂,而只是我们用编辑器自己来写文档的话,不仅工作量大,而且容易出错,出错后前端人员还要再来找你沟通,所以我们这里引入了swagger,它的作用是能生成接口文档
在pom.xml文件中引入依赖
这里引入2.9.2的版本,因为它比较稳定
<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
@Component
@EnableSwagger2
public class SwaggerConfig {
}
可以在这个类里面写一下自己对swagger的配置,也可以不配置,如果不配质可以直接在,主程序的main方法的类型上加上@EnableSwagger2也能开启swagger2
启动程序后访问:http://localhost:8080/swagger-ui.html
注解的说明
@RestController
@Api(value = "用户管理", tags = "欢迎controller")
public class DepartmentController {
@Resource
private DepartmentService departmentService;
@ApiOperation(value = "增加一个用户",notes = "增加用户信息")
@PostMapping(value = "addDepartment")
public R addDepartment(@RequestBody Department department) throws Exception {
return R.success(departmentService.addDepartment(department));
}
//,tags = "删除" 直接多出一个控制层的感觉
@ApiOperation(value = "根据id删除部门",notes = "删除部门")
@ApiImplicitParam(name = "id",value = "部门id")
@GetMapping("removeDepartment")
public R removeDepartment(@RequestParam(value = "id",required = true) Integer id) throws Exception {
return R.success(departmentService.removeDepartment(id));
}
//method = RequestMethod.POST和@POSTMapping效果一样
@ApiOperation(value = "修改用户")
@RequestMapping(value = "modifyDepartment",method = RequestMethod.POST)
public R modifyDepartment(Department department)throws Exception{
return R.success(departmentService.modifyDepartment(department));
}
@ApiOperation(value = "获取部门列表",notes = "获取所有部门信息")
@GetMapping("returnAllDepartment")
public R returnAllDepartment()throws Exception{
System.out.println(1);
return R.success(departmentService.findALL());
}
@ApiOperation(value = "根据id查找部门")
@ApiImplicitParam(name = "id",value = "部门id")
@GetMapping("returnOneDepartment/{id}")
public R returnOneDepartment(@PathVariable("id")Integer id) throws Exception {
return R.success(departmentService.findOne(id));
}
@ApiOperation(value = "查询部门含有员工信息")
@ApiImplicitParam(name = "name",value = "部门名称")
@GetMapping("returnDepWithEmp/{name}")
public R returnDepWithEmp(@PathVariable("name")String name) throws Exception {
return R.success(departmentService.findDemWithEmp(name));
}
@ApiOperation(value = "查询该部门下有多少男人或女人")
@ApiImplicitParams({
@ApiImplicitParam(name = "name",value = "部门名称"),
@ApiImplicitParam(name = "sex",value = "性别")
})
@GetMapping("findDemWithEmpBySex/{name}/{sex}")
public R findDemWithEmpBySex(@PathVariable("name")String name,@PathVariable("sex")String sex) throws Exception {
return R.success(departmentService.findDemWithEmpBySex(name, sex));
}
@ApiOperation(value = "根据部门名称得到该部门下的员工")
@ApiImplicitParam(name = "name",value = "部门名称")
@GetMapping("returnEmployeesByDepID/{name}")
public R returnEmployees(@PathVariable("name")String name) throws Exception {
return R.success(departmentService.findEmployeeByDepName(name));
}
}
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel
public class Department {
@ApiModelProperty("部门id")
private Integer id;
@ApiModelProperty("部门创建时间")
private Date create_time;
@ApiModelProperty("部门修改时间")
private Date update_time;
@ApiModelProperty("部门名称")
private String department_name;
@ApiModelProperty("该部门下所含员工")
private List<Employee> employees;
}
各个注解的详细说明
- @Api注解可以用来标记当前Controller的功能。
- @ApiOperation注解用来标记一个方法的作用。
- @ApiImplicitParam注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入。
- 如果有多个参数,则需要使用多个@ApiImplicitParam注解来描述,多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
- 需要注意的是,@ApiImplicitParam注解中虽然可以指定参数是必填的,但是却不能代替@RequestParam(required = true),前者的必填只是在Swagger2框架内必填,抛弃了Swagger2,这个限制就没用了,所以假如开发者需要指定一个参数必填,@RequestParam(required = true)注解还是不能省略。
- 如果参数是一个对象(例如上文的更新接口),对于参数的描述也可以放在实体类中。例如下面一段代码: