Spring Boot中OpenApi自定义分页参数仅对含Pageable方法生效的实现

要实现仅对包含Pageable参数的接口添加分页参数，你可以通过HandlerMethod检查目标方法的参数列表，判断是否存在org.springframework.data.domain.Pageable类型的参数，再决定是否添加分页参数。同时建议移除自动生成的pageable参数，避免UI中出现重复内容。

修改后的代码如下：

public OperationCustomizer parameterCustomizer() {
    return (Operation operation, HandlerMethod handlerMethod) -> {
        // 检查方法参数是否包含Pageable类型
        boolean hasPageableParameter = Arrays.stream(handlerMethod.getMethodParameters())
                .anyMatch(param -> param.getParameterType().equals(org.springframework.data.domain.Pageable.class));

        if (hasPageableParameter) {
            // 移除自动生成的pageable参数（避免重复展示）
            operation.getParameters().removeIf(param -> "pageable".equals(param.getName()));

            // 构建分页参数
            Parameter page = new Parameter()
                    .in(ParameterIn.QUERY.toString())
                    .schema(new IntegerSchema()._default(0))
                    .name("page")
                    .description("La page (0..N)")
                    .required(true);
            Parameter size = new Parameter()
                    .in(ParameterIn.QUERY.toString())
                    .schema(new IntegerSchema()._default(10))
                    .name("pageSize")
                    .description("Nombre de résultats par page")
                    .required(true);
            Parameter sort = new Parameter()
                    .in(ParameterIn.QUERY.toString())
                    .schema(new ArraySchema().items(new StringSchema()))
                    .name("sort")
                    .description("Critère de tri avec le format: property(,asc|desc). "
                            + "Tri par défaut: ascendant. "
                            + "Multiple critères de tri sont supportés.");

            // 添加分页参数
            operation.addParametersItem(page);
            operation.addParametersItem(size);
            operation.addParametersItem(sort);
        }
        return operation;
    };
}

关键说明： #

• 检查Pageable参数：通过handlerMethod.getMethodParameters()获取方法的所有参数，遍历判断是否有Pageable类型的参数，只有存在时才执行后续逻辑。
• 移除默认pageable参数：OpenAPI会自动为Pageable参数生成一个名为pageable的复合参数，需要先移除它，避免UI中同时显示原始复合参数和拆分后的分页参数。
• 完善sort参数的Schema：原代码中sort的ArraySchema没有指定元素类型，这里补充items(new StringSchema())，让UI能正确识别参数格式。

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