如何在Spring Rest Docs 3.x中修改请求参数？

Spring Rest Docs 3.x移除了原有用于修改请求参数的预处理器，官方未在发布说明中明确替代方案，以下是两种可行的实现方式：

方式一：测试时直接指定文档展示的参数 #

在发送测试请求时，直接传入希望在文档中呈现的参数值（比如脱敏后的敏感参数），无需额外预处理：

mockMvc.perform(get("/api/users")
        .param("page", "1")
        .param("size", "10")
        // 直接传入文档需要展示的参数值，而非真实测试用的敏感值
        .param("api-key", "***"))
        .andDo(document("users-list",
                requestParameters(
                        parameterWithName("page").description("页码"),
                        parameterWithName("size").description("每页数量"),
                        parameterWithName("api-key").description("API密钥（已脱敏）")
                )
        ));

这种方式简单直接，适合大多数场景，也是官方更推荐的做法——让测试请求的参数直接匹配文档需要展示的内容。

方式二：自定义OperationPreprocessor实现参数修改 #

如果需要在不修改测试请求参数的前提下调整文档中的参数展示，可以自定义请求预处理器：

1. 实现自定义预处理器类 #

import org.springframework.restdocs.operation.Operation;
import org.springframework.restdocs.operation.OperationRequest;
import org.springframework.restdocs.operation.OperationRequestFactory;
import org.springframework.restdocs.operation.preprocess.OperationPreprocessor;

import java.util.LinkedHashMap;
import java.util.Map;

public class RequestParameterModifier implements OperationPreprocessor {

    private final Map<String, String> parameterReplacements;

    public RequestParameterModifier(Map<String, String> parameterReplacements) {
        this.parameterReplacements = parameterReplacements;
    }

    @Override
    public Operation preprocess(Operation operation) {
        OperationRequest originalRequest = operation.getRequest();
        // 复制原请求参数，避免修改原对象
        Map<String, String[]> modifiedParameters = new LinkedHashMap<>(originalRequest.getParameters());

        // 批量替换目标参数
        parameterReplacements.forEach((key, replacementValue) -> {
            if (modifiedParameters.containsKey(key)) {
                modifiedParameters.put(key, new String[]{replacementValue});
            }
        });

        // 构建修改后的请求对象
        OperationRequest modifiedRequest = new OperationRequestFactory().create(
                originalRequest.getUri(),
                originalRequest.getMethod(),
                originalRequest.getContent(),
                modifiedParameters,
                originalRequest.getHeaders(),
                originalRequest.getAttributes()
        );

        // 返回包含修改后请求的Operation
        return new Operation(modifiedRequest, operation.getResponse(), operation.getAttributes());
    }
}

2. 在测试配置中应用预处理器 #

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;

@BeforeEach
void setUp() {
    this.mockMvc = MockMvcBuilders.standaloneSetup(new UserController())
            .apply(documentationConfiguration(this.restDocumentation)
                    // 注册自定义请求预处理器
                    .operationPreprocessors()
                    .withRequestPreprocessor(new RequestParameterModifier(Map.of(
                            "api-key", "***",
                            "secret-token", "xxx"
                    ))))
            .build();
}

@Test
void listUsers() throws Exception {
    // 测试请求使用真实参数，但文档中会被预处理器替换
    mockMvc.perform(get("/api/users")
            .param("page", "1")
            .param("size", "10")
            .param("api-key", "real-sensitive-key")
            .param("secret-token", "actual-secret-token"))
            .andDo(document("users-list",
                    requestParameters(
                            parameterWithName("page").description("页码"),
                            parameterWithName("size").description("每页数量"),
                            parameterWithName("api-key").description("API密钥（已脱敏）"),
                            parameterWithName("secret-token").description("认证令牌（已脱敏）")
                    )
            ));
}

这种方式适合需要保留真实测试参数，但文档中需调整展示内容的场景，灵活性更高。

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