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/”);

  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值