如何在Swagger UI中设置或隐藏Pageable查询参数默认值？

问题原因 #

Swagger（无论是SpringDoc还是旧版Springfox）默认会给Pageable类型参数生成固定默认值（比如page=0、size=20），但不会自动读取你通过@PageableDefault设置的自定义默认值，因此出现显示不符合预期的情况。

解决方案 #

情况1：使用SpringDoc（Spring Boot 2.6+推荐） #

SpringDoc是当前Spring官方推荐的Swagger实现，以下两种方式可选：

方式1：让Swagger识别@PageableDefault的自定义默认值

创建自定义操作处理器，读取@PageableDefault配置并同步到Swagger参数中：

import io.swagger.v3.oas.models.Operation;
import io.swagger.v3.oas.models.parameters.Parameter;
import org.springdoc.core.customizers.OperationCustomizer;
import org.springframework.data.web.PageableDefault;
import org.springframework.stereotype.Component;
import org.springframework.web.method.HandlerMethod;

import java.util.List;

@Component
public class PageableSwaggerCustomizer implements OperationCustomizer {

    @Override
    public Operation customize(Operation operation, HandlerMethod handlerMethod) {
        handlerMethod.getMethodParameters().forEach(methodParam -> {
            if (org.springframework.data.domain.Pageable.class.isAssignableFrom(methodParam.getParameterType())) {
                PageableDefault pageableDefault = methodParam.getParameterAnnotation(PageableDefault.class);
                if (pageableDefault != null) {
                    List<Parameter> swaggerParams = operation.getParameters();
                    swaggerParams.forEach(param -> {
                        switch (param.getName()) {
                            case "page":
                                param.setDefaultValue(String.valueOf(pageableDefault.page()));
                                break;
                            case "size":
                                param.setDefaultValue(String.valueOf(pageableDefault.size()));
                                break;
                            case "sort":
                                if (pageableDefault.sort().length > 0) {
                                    param.setDefaultValue(pageableDefault.sort()[0] + "," + pageableDefault.direction());
                                }
                                break;
                        }
                    });
                }
            }
        });
        return operation;
    }
}

启动项目后，Swagger页面的Pageable参数就会显示你设置的默认值。

方式2：隐藏Pageable的所有默认值

如果不需要显示任何默认值，可通过配置文件修改：

springdoc:
  swagger-ui:
    # 隐藏模型默认展开深度，间接隐藏默认值显示
    default-model-expand-depth: -1

或者在上面的自定义处理器中，将param.setDefaultValue()改为param.setDefaultValue(null)，也能达到隐藏效果。

情况2：使用Springfox（旧版本Swagger） #

若项目仍在使用Springfox，需自定义参数插件覆盖默认行为：

方式1：自定义Pageable参数的默认值

创建插件类：

import org.springframework.data.domain.Pageable;
import org.springframework.data.web.PageableDefault;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.OperationBuilderPlugin;
import springfox.documentation.spi.service.contexts.OperationContext;

import java.util.ArrayList;
import java.util.List;

public class PageableParameterPlugin implements OperationBuilderPlugin {

    @Override
    public void apply(OperationContext context) {
        context.getParameters().forEach(param -> {
            if (param.getParameterType().getType().equals(Pageable.class)) {
                PageableDefault pageableDefault = param.getParameterAnnotation(PageableDefault.class);
                int defaultPage = pageableDefault != null ? pageableDefault.page() : 0;
                int defaultSize = pageableDefault != null ? pageableDefault.size() : 20;
                String defaultSort = pageableDefault != null && pageableDefault.sort().length > 0
                        ? pageableDefault.sort()[0] + "," + pageableDefault.direction()
                        : null;

                List<Parameter> customParams = new ArrayList<>();
                customParams.add(new ParameterBuilder()
                        .name("page")
                        .description("页码（从0开始）")
                        .defaultValue(String.valueOf(defaultPage))
                        .modelRef(new ModelRef("integer"))
                        .parameterType("query")
                        .required(false)
                        .build());
                customParams.add(new ParameterBuilder()
                        .name("size")
                        .description("每页数据量")
                        .defaultValue(String.valueOf(defaultSize))
                        .modelRef(new ModelRef("integer"))
                        .parameterType("query")
                        .required(false)
                        .build());
                customParams.add(new ParameterBuilder()
                        .name("sort")
                        .description("排序规则，格式：字段名,asc/desc")
                        .defaultValue(defaultSort)
                        .modelRef(new ModelRef("string"))
                        .parameterType("query")
                        .required(false)
                        .build());
                context.operationBuilder().parameters(customParams);
            }
        });
    }

    @Override
    public boolean supports(DocumentationType documentationType) {
        return true;
    }
}

然后在Swagger配置类中注册这个插件：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.spi.service.OperationBuilderPlugin;

@Configuration
public class SwaggerConfig {
    @Bean
    public OperationBuilderPlugin pageableParameterPlugin() {
        return new PageableParameterPlugin();
    }
}

方式2：隐藏默认值

只需在上面的ParameterBuilder中去掉.defaultValue()的设置，或者将参数设为null，Swagger页面就不会显示默认值了。

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