SpringBoot整合Swagger2生成接口API文档

前言：Swagger2是一个能够帮助我们快速生成RESTful接口API文档的一个工具，你可以在控制器上写上接口描述，参数描述等等，在生成的Swagger2接口文档中都有体现，而且还可以在该文档上进行对接口的调用测试，能看见接口参数，头信息，返回值等等。给我们开发人员开发提供了便捷。

1.导入依赖：

        <!---Swagger2 在线文档配置-->
        <!--swagger本身不支持spring mvc的，springfox把swagger包装了一下，让他可以支持springmvc-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>

2.swagger2配置类：

/**
 * 通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。
 * 再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。
 * select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义
 * Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //要扫描的API基础包
                .apis(RequestHandlerSelectors.basePackage("com.example.consumer.controller"))
                .paths(PathSelectors.any())
                .build();
    }


    /**
     * 构建API基本信息
     * @return springfox.documentation.service.ApiInfo
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("学生示例接口API文档")
                .description("API文档主要包含RESTFUL API  请求")
                // 设置文档的License信息
                .termsOfServiceUrl("NO terms of service")
                .contact(new Contact("zks",null,null))
                .version("1.0")
                .build();
    }

}

3.控制器示例：

/**
 * @Description：学生控制器
 * @Author :zks
 * @Date :10:51 2020/9/15
 */
@RestController
@RequestMapping("student")
public class StudentController {

    @Autowired
    private IStudentInfoService studentInfoService;

    /**
     * 保存学生信息
     * @param studentInfo
     * @return
     */
    @ApiOperation(value = "保存学生信息")
    @PostMapping("save")
    public Result save(@ApiParam(value = "学生实体信息") @RequestBody StudentInfo studentInfo){
        studentInfoService.save(studentInfo);
        return Result.success();
    }

    /**
     * 根据主键id查找学生信息
     * @param id
     * @return
     */
    @ApiOperation(value = "根据主键id查找学生信息")
    @GetMapping("getStudentInfoById")
    public Result getStudentInfoById(@ApiParam(value = "学生主键id") @RequestParam("id") ObjectId id){
        StudentInfo studentInfo=studentInfoService.getStudentInfoById(id);
        return Result.success(studentInfo);
    }

    /**
     * 根据所选课程id查找学生信息列表并分页
     * @param courseId
     * @param page
     * @param limit
     * @param sort
     * @param order
     * @return
     */
    @ApiOperation(value = "根据所选课程id查找学生信息列表并分页")
    @GetMapping("getStudentInfoListByCourseId")
    public Result getStudentInfoListByCourseId(@ApiParam(value = "所选课程id") @RequestParam("courseId")Integer courseId,
                                               @ApiParam(value = "从第几页开始列出") @RequestParam(defaultValue = "1") Integer page,
                                               @ApiParam(value = "一页显示数") @RequestParam(defaultValue = "10") Integer limit,
                                               @ApiParam(value = "排序字段") @RequestParam(defaultValue = "addTime") String sort,
                                               @ApiParam(value = "排序方式") @RequestParam(defaultValue = "desc") String order){
        List<StudentInfo> studentInfoList = studentInfoService.getStudentInfoListByCourseId(courseId, page, limit, sort, order);
        return Result.success(studentInfoList);
    }

    /**
     * 更新学生信息
     * @param studentInfo
     * @return
     */
    @ApiOperation(value = "更新学生信息")
    @PostMapping("update")
    public Result update(@ApiParam(value = "学生信息") @RequestBody StudentInfo studentInfo){
        studentInfoService.update(studentInfo);
        return Result.success();
    }

    /**
     * 根据学生id以及课程id删除选修课程
     * @param id
     * @param courseId
     * @return
     */
    @ApiOperation(value = "根据学生id以及课程id删除选修课程")
    @GetMapping("deleteCourseByIdAndCourseId")
    public Result deleteCourseByIdAndCourseId(@ApiParam(value = "学生主键id") @RequestParam("id") ObjectId id,
                                              @ApiParam(value = "课程id") @RequestParam("courseId") Integer courseId){
        studentInfoService.deleteCourseByIdAndCourseId(id,courseId);
        return Result.success();
    }

    /**
     * 删除学生信息
     * @param id
     * @return
     */
    @ApiOperation(value = "删除学生信息")
    @GetMapping("delete")
    public Result delete(@ApiParam(value = "学生主键id") @RequestParam("id") ObjectId id){
        studentInfoService.delete(id);
        return Result.success();
    }


}

4.默认访问地址ip+端口+/swagger-ui.html（示例：http://localhost:8080/swagger-ui.html），即可查看Swagger2接口文档：

5.@ApiOperation接口描述以及@ApiParam参数描述：