Spring Boot项目中Open API 3.0分页排序的默认参数配置方法

要自定义默认分页大小和排序规则，确实需要做针对性配置，分为Spring Data JPA分页排序核心配置和Springdoc接口文档适配两部分：

一、配置Spring Data JPA的默认分页与排序 #

方式1：通过配置文件快速设置（推荐简单场景） #

直接在application.yml或application.properties中添加配置，无需编写代码：

application.yml示例：

spring:
  data:
    web:
      pageable:
        default-page-size: 10  # 默认每页展示10条数据
        max-page-size: 100     # 限制最大每页条数（可选）
        one-indexed-parameters: false # 是否启用1-based页码（默认是0-based，即第一页为0）
      sort:
        default-sort: id,desc  # 默认排序规则：按id字段降序排列

application.properties示例：

spring.data.web.pageable.default-page-size=10
spring.data.web.pageable.max-page-size=100
spring.data.web.pageable.one-indexed-parameters=false
spring.data.web.sort.default-sort=id,desc

方式2：自定义参数解析器（适合复杂/个性化场景） #

如果需要针对不同接口设置不同默认值，或动态调整规则，可以自定义PageableHandlerMethodArgumentResolver和SortHandlerMethodArgumentResolver：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.domain.Sort;
import org.springframework.data.web.PageableHandlerMethodArgumentResolver;
import org.springframework.data.web.SortHandlerMethodArgumentResolver;

@Configuration
public class WebDataConfig {

    @Bean
    public PageableHandlerMethodArgumentResolver pageableResolver() {
        PageableHandlerMethodArgumentResolver resolver = new PageableHandlerMethodArgumentResolver(sortResolver());
        resolver.setDefaultPageSize(10); // 默认每页条数
        resolver.setOneIndexedParameters(true); // 启用1-based页码（第一页为1）
        resolver.setMaxPageSize(100); // 最大允许每页条数
        return resolver;
    }

    @Bean
    public SortHandlerMethodArgumentResolver sortResolver() {
        SortHandlerMethodArgumentResolver resolver = new SortHandlerMethodArgumentResolver();
        // 设置默认排序：按createTime字段降序
        resolver.setDefaultSort(Sort.by(Sort.Direction.DESC, "createTime"));
        return resolver;
    }
}

二、Springdoc Open Api 3.0适配（让文档显示默认值） #

为了让接口文档的分页参数（page/size/sort）显示默认值，方便前端开发者参考，可通过以下两种方式配置：

方式1：全局配置参数默认值 #

创建OpenApi配置类，统一设置分页参数的默认值和描述：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.parameters.Parameter;
import io.swagger.v3.oas.models.servers.Server;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.List;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        Parameter pageParam = new Parameter()
                .name("page")
                .in("query")
                .description("页码，默认0（若启用1-based则为1）")
                .schema(new io.swagger.v3.oas.models.media.IntegerSchema().defaultValue(0));

        Parameter sizeParam = new Parameter()
                .name("size")
                .in("query")
                .description("每页条数，默认10")
                .schema(new io.swagger.v3.oas.models.media.IntegerSchema().defaultValue(10));

        Parameter sortParam = new Parameter()
                .name("sort")
                .in("query")
                .description("排序规则，默认id,desc")
                .schema(new io.swagger.v3.oas.models.media.StringSchema().defaultValue("id,desc"));

        return new OpenAPI()
                .servers(List.of(new Server().url("/")))
                .components(new io.swagger.v3.oas.models.Components()
                        .addParameters("pageParam", pageParam)
                        .addParameters("sizeParam", sizeParam)
                        .addParameters("sortParam", sortParam));
    }
}

方式2：在Controller方法上单独设置 #

如果仅需针对特定接口配置，可在方法参数上添加@Parameter注解：

import io.swagger.v3.oas.annotations.Parameter;
import org.springframework.data.domain.Pageable;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class DemoController {

    @GetMapping("/items")
    public String getItems(
            @Parameter(description = "页码，默认1", schema = @io.swagger.v3.oas.annotations.media.Schema(defaultValue = "1")) 
            Pageable pageable) {
        // 业务逻辑实现
        return "items list";
    }
}

内容的提问来源于stack exchange，提问作者Ash