SpringBoot整合Swagger2生成接口API文档

r囧r小猫 2022-12-07 12:08 303阅读 0赞

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

**1.导入依赖：**

<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接口文档：**

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDAwOTQ0Nw_size_16_color_FFFFFF_t_70_pic_center]  
**5.@ApiOperation接口描述以及@ApiParam参数描述：**

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDAwOTQ0Nw_size_16_color_FFFFFF_t_70_pic_center 1]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDAwOTQ0Nw_size_16_color_FFFFFF_t_70_pic_center]: /images/20221123/b3ef596af5e0411fafd30099550060ff.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDAwOTQ0Nw_size_16_color_FFFFFF_t_70_pic_center 1]: /images/20221123/bf44e47af3de4ee98e130e03c100ab0a.png