3步自动生成分页API文档：Swagger+Mybatis-PageHelper实战指南-优快云博客

3步自动生成分页API文档：Swagger+Mybatis-PageHelper实战指南

【免费下载链接】Mybatis-PageHelper Mybatis通用分页插件项目地址: https://gitcode.com/gh_mirrors/my/Mybatis-PageHelper

你是否还在手动编写分页接口文档？是否因API参数更新不及时导致前后端协作效率低下？本文将带你通过3个步骤实现分页API文档的自动生成，结合Swagger与Mybatis-PageHelper，让接口文档维护从此自动化、标准化。

读完本文你将获得：

掌握PageHelper核心分页参数的自动文档生成
学会使用Swagger注解描述复杂分页响应结构
实现分页接口文档与代码的实时同步

技术准备：核心组件与依赖

Mybatis-PageHelper作为MyBatis生态中最流行的分页插件，其核心能力由src/main/java/com/github/pagehelper/PageHelper.java实现拦截器逻辑，通过src/main/java/com/github/pagehelper/Page.java封装分页参数与结果。要实现文档自动生成，需添加以下依赖：

<!-- Swagger核心依赖 -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>
<!-- Mybatis-PageHelper -->
<dependency>
  <groupId>com.github.pagehelper</groupId>
  <artifactId>pagehelper-spring-boot-starter</artifactId>
  <version>1.4.6</version>
</dependency>

图：MyBatis分页插件与Swagger集成架构示意图

第一步：配置Swagger文档基础信息

创建Swagger配置类，指定API文档的基本信息和扫描路径。关键在于通过@Bean定义Docket对象时，需排除PageHelper的内部类，避免生成无关文档：

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yourpackage.controller"))
                .paths(PathSelectors.any())
                .build()
                // 忽略PageHelper的内部方法
                .ignoredParameterTypes(Page.class, PageInfo.class);
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("分页API自动文档")
                .description("基于Swagger和Mybatis-PageHelper实现")
                .version("1.0.0")
                .build();
    }
}

配置类需放置在SpringBoot应用能扫描到的路径下，通常与主启动类同级。更多配置选项可参考wikis/zh/HowToUse.md中的高级配置章节。

第二步：分页接口的Swagger注解实战

以用户管理模块为例，展示如何为分页接口添加Swagger注解。核心是使用@ApiImplicitParams描述分页参数，@ApiOperation说明接口功能，@ApiResponses定义响应结构：

@RestController
@RequestMapping("/users")
@Api(tags = "用户管理")
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping
    @ApiOperation("分页查询用户列表")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "pageNum", value = "页码（从1开始）", 
                        dataTypeClass = Integer.class, paramType = "query", 
                        defaultValue = "1", example = "1"),
        @ApiImplicitParam(name = "pageSize", value = "每页条数", 
                        dataTypeClass = Integer.class, paramType = "query", 
                        defaultValue = "10", example = "10"),
        @ApiImplicitParam(name = "keyword", value = "搜索关键词", 
                        dataTypeClass = String.class, paramType = "query")
    })
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "成功", 
                    content = @Content(schema = @Schema(implementation = PageInfo.class)))
    })
    public PageInfo<User> list(
            @RequestParam(defaultValue = "1") int pageNum,
            @RequestParam(defaultValue = "10") int pageSize,
            String keyword) {
        // 使用PageHelper.startPage开启分页
        PageHelper.startPage(pageNum, pageSize);
        List<User> users = userService.search(keyword);
        return new PageInfo<>(users);
    }
}

上述代码中，PageInfo<User>作为返回类型会被Swagger自动解析，生成包含总页数、当前页数据等完整分页信息的文档。实体类User需添加@ApiModel注解增强文档可读性：

@Data
@ApiModel(description = "用户信息")
public class User {
    @ApiModelProperty(value = "用户ID", example = "1001")
    private Long id;
    
    @ApiModelProperty(value = "用户名", required = true, example = "张三")
    private String username;
    
    @ApiModelProperty(value = "创建时间", format = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime createTime;
}

第三步：分页响应结构的高级配置

Mybatis-PageHelper提供了两种核心分页结果封装类：Page和PageInfo。其中src/main/java/com/github/pagehelper/PageInfo.java包含更丰富的分页元数据，适合作为API返回类型。通过Swagger的@Schema注解可自定义其文档展示：

@Getter
@Setter
@ApiModel(description = "分页结果封装")
public class PageInfo<T> {
    @ApiModelProperty(value = "当前页码", example = "1")
    private int pageNum;
    
    @ApiModelProperty(value = "每页条数", example = "10")
    private int pageSize;
    
    @ApiModelProperty(value = "总记录数", example = "100")
    private long total;
    
    @ApiModelProperty(value = "总页数", example = "10")
    private int pages;
    
    @ApiModelProperty(value = "当前页数据")
    private List<T> list;
    
    // 省略其他字段和方法
}

实际项目中，推荐创建统一的API响应类包装PageInfo，如：

@Data
@ApiModel(description = "API统一响应")
public class ApiResponse<T> {
    @ApiModelProperty(value = "状态码", example = "200")
    private int code;
    
    @ApiModelProperty(value = "消息", example = "操作成功")
    private String message;
    
    @ApiModelProperty(value = "数据")
    private T data;
    
    // 成功响应构造方法
    public static <T> ApiResponse<T> success(T data) {
        ApiResponse<T> response = new ApiResponse<>();
        response.setCode(200);
        response.setMessage("success");
        response.setData(data);
        return response;
    }
}

文档测试与高级功能

启动应用后访问http://localhost:8080/swagger-ui/index.html即可看到自动生成的API文档。测试分页接口时，Swagger会提供交互式参数表单，方便前后端开发人员进行联调。

对于复杂场景，可通过以下方式增强文档能力：

自定义参数校验：结合@Validated和@Min等注解，Swagger会自动生成参数校验规则说明
添加响应示例：使用@ExampleObject注解为字段提供多组示例值
接口权限控制：通过Swagger的SecurityScheme配置API访问授权

图：Swagger UI中的分页接口文档示例

总结与最佳实践

通过本文介绍的3个步骤，我们实现了分页API文档的自动生成。核心要点包括：

依赖配置：正确引入Swagger和PageHelper依赖
注解使用：合理运用@ApiOperation、@ApiImplicitParams等注解
响应封装：统一API响应格式，增强文档可读性

最佳实践建议：

为所有分页接口添加默认参数值，提升文档易用性
在CI/CD流程中集成Swagger文档导出，自动更新API文档站点
定期清理未使用的Swagger注解，保持代码整洁

Mybatis-PageHelper的更多高级特性，如动态数据源分页、异步count查询等，都可通过类似方式生成文档。希望本文能帮助你提升API文档维护效率，让团队协作更顺畅！

点赞+收藏本文，关注作者获取更多MyBatis实战技巧。下期预告：《PageHelper性能优化指南》

【免费下载链接】Mybatis-PageHelper Mybatis通用分页插件项目地址: https://gitcode.com/gh_mirrors/my/Mybatis-PageHelper

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考