SpringBoot整合Swagger

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;

}

各个注解的详细说明

1. @Api注解可以用来标记当前Controller的功能。
2. @ApiOperation注解用来标记一个方法的作用。
3. @ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
4. 如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
5. 需要注意的是，@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略。
6. 如果参数是一个对象（例如上文的更新接口），对于参数的描述也可以放在实体类中。例如下面一段代码：

如果有拦截器需要这样放行.excludePathPatterns("/swagger-resources/", "/webjars/", “/v2/", "/swagger-ui.html/”);