SpringBoot集成Swagger2 #yyds干货盘点#

Posted 2021-12-03 梁云亮

第一步：添加Maven依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--Swagger2在线文档-->
<!--swagger2本身不支持spring mvc的，springfox把swagger包装了一下，让他可以支持springmvc-->
<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>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.3</version>
</dependency>

第二步：编写Swagger配置类，代码如下：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 自行修改为自己的包路径
                .apis(RequestHandlerSelectors.basePackage("com.hc.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("客户管理")
                .description("客户管理中心 API 1.0 操作文档")
                //服务条款网址
                .termsOfServiceUrl("http://www.hcit.com/")
                .version("1.0")
                .contact(new Contact("客户中心", "http://www.hcit.com/", "[e-mail]"))
                .build();
    }
}

第三步：编写实体类：

@ApiModel(value = "Dept",description = "部门信息")
public class Dept {
    @ApiModelProperty("部门编号")
    private int deptno;
    @ApiModelProperty("部门名称")
    private String dname;
    @ApiModelProperty("部门地址")
    private String loc;
    //……getter/setter、toString()、全参和默认构造方法
}

第四步：Controller层代码

@RestController
@RequestMapping(value = "/dept")
@Api(value = "DeptController-部门接口模拟", tags = "DeptController-部门接口模拟")
//@ApiResponses({
//        @ApiResponse(code = 200, message = "OK"),
//        @ApiResponse(code = 400, message = "客户端请求错误"),
//        @ApiResponse(code = 404, message = "找不到路径"),
//        @ApiResponse(code = 500, message = "编译异常")
//})
public class DeptController {

    private List<Dept> deptList;

    {  //初始化
        deptList = new ArrayList<>();
        for (int i = 0; i < 10; i++) {
            Dept dept = new Dept();
            dept.setDeptno(i);
            dept.setDname("dname_" + i);
            dept.setLoc("loc_" + i);
            deptList.add(dept);
        }
    }

//    @PostMapping(value = "/add")
    @RequestMapping(value = "/add", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE)
    @ApiOperation(value = "添加部门信息", notes = "", httpMethod = "POST")
    public List<Dept> addDept(@RequestBody Dept dept) throws Exception {
        deptList.add(dept);
        return deptList;
    }

    @RequestMapping(value = "/delete/{deptno}", method = RequestMethod.DELETE)
    @ApiOperation(value = "删除部门信息", notes = "")
    //不知道为什么此处写成path会报错
    @ApiImplicitParam(paramType = "delete", name = "deptno", value = "部门ID", required = true, dataType = "int")
    public List<Dept> deleteDept(@PathVariable(value = "deptno") Integer deptno) {
        for (int i = 0; i < deptList.size(); i++) {
            if (deptList.get(i).getDeptno() == deptno) {
                deptList.remove(i);
            }
        }
        return deptList;
    }

    @PutMapping(value = "/updateDept1/{deptno}")
    @ApiOperation(value = "修改部门信息", notes = "", httpMethod = "PUT")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "path", name = "deptno", value = "部门ID", required = true, dataType = "Integer"),
            @ApiImplicitParam(name = "dept", value = "用户实体,传入更改后的数据", required = true, dataType = "Dept")
    })
    public List<Dept> updateDept1(@PathVariable(value = "deptno", required = true) Integer deptno, @RequestBody Dept dept) {
        for (int i = 0; i < deptList.size(); i++) {
            if (deptList.get(i).getDeptno() == deptno) {
                deptList.add(i, dept);
                break;
            }
        }
        return deptList;
    }

    @PostMapping("/updateDept2")
    @ApiOperation(value = "修改部门地址", notes = "根据部门编号修改部门地址")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "deptno", value = "部门ID", required = true, dataType = "Integer"),
            @ApiImplicitParam(paramType = "query", name = "dname", value = "部门名称", required = true, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "loc", value = "部门地址", required = true, dataType = "String")
    })
    public List<Dept> updateDept2(@RequestParam(value = "deptno") Integer deptno,
                                  @RequestParam(value = "dname") String dname,
                                  @RequestParam(value = "loc") String loc) {
        for (int i = 0; i < deptList.size(); i++) {
            if (deptList.get(i).getDeptno() == deptno) {
                deptList.add(i, new Dept(deptno, dname, loc));
                break;
            }
        }
        return deptList;
    }

    @GetMapping(value = "/list")
    @ApiOperation(value = "获取部门列表", notes = "一次全部取，不分页", httpMethod = "GET")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "header", name = "token", value = "token", required = true, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "pageNum", value = "当前页数", required = false, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "pageSize", value = "每页记录数", required = true, dataType = "String"),
    })
    public List<Dept> getDoctorList(@RequestParam(value = "pageNum", required = false, defaultValue = "1") Integer pageIndex,
                                    @RequestParam(value = "pageSize", required = false) Integer pageSize) throws RuntimeException {
        return deptList;
    }

    @GetMapping(value = "/getDeptByDeptno1/{deptno}", produces = MediaType.APPLICATION_JSON_VALUE)
    @ApiOperation(value = "获取部门详细信息", notes = "根据url的deptno来获取部门详细信息", httpMethod = "GET")
    @ApiImplicitParam(name = "deptno", value = "部门ID", required = true, dataType = "Integer", paramType = "path")
    public Dept getDeptByDeptno1(@PathVariable Integer deptno) {
        return deptList.get(deptno);
    }

    @GetMapping(value = "/getDeptByDeptno2/{deptno}", produces = MediaType.APPLICATION_JSON_VALUE)
    @ApiOperation(value = "获取部门详细信息", notes = "根据url的deptno来获取部门详细信息", httpMethod = "GET")
    public Dept getDeptByDeptno2(@PathVariable Integer deptno) {
        return deptList.get(deptno);
    }

    @RequestMapping(value = "/getDeptByDeptno3", method = RequestMethod.GET)
    @ApiOperation(value = "获取部门详细信息", notes = "根据id获取部门详细信息")
    @ApiImplicitParam(paramType = "query", name = "deptno", value = "部门ID", required = true, dataType = "Integer")
    public Dept getDeptByDeptno3(@RequestParam Integer deptno) {
        return deptList.get(deptno);
    }

}

部署项目运行查看结果

网址：http://localhost/is/swagger-ui.html

网址：http://localhost/is/doc.html