Spring RESTDocs报错：请求中未找到指定Query参数求助

问题描述 #

在Spring 3.3.2环境下使用Spring RESTDocs生成API文档时，遇到如下报错：

Query parameters with the following names were not found in the request: [password, driverId, loginState, regId, deviceDiv]
org.springframework.restdocs.snippet.SnippetException: Query parameters with the following names were not found in the request: [password, driverId, loginState, regId, deviceDiv]

相关测试代码：

@DisplayName("기사 로그인 API")
@Test
void checkMatchLogin() throws Exception {
    //given
    given(driverService.driverLogin(
        anyInt(),
        anyString(),
        anyInt(),
        anyInt(),
        anyString(),
        anyString())).willReturn("true");

    mockMvc.perform(
            // when
            RestDocumentationRequestBuilders.post("/api/driver/login")
                .param("driverId", "2")
                .param("password", "2222")
                .param("loginState", "1")
                .param("deviceDiv", "1")
                .param("regId", "please_input_gcm_code")
        )

        // then
        .andDo(print())
        .andExpect(status().isOk())
        .andDo(document("driver-login",
            preprocessResponse(prettyPrint()),
            queryParameters(
                parameterWithName("driverId").description("driverId"),
                parameterWithName("password").description("password"),
                parameterWithName("loginState").description("loginState"),
                parameterWithName("deviceDiv").description("deviceDiv"),
                parameterWithName("regId").description("GCM Key")
            ),
            responseFields(
                fieldWithPath("code").type(JsonFieldType.NUMBER)
                    .description("code"),
                fieldWithPath("message").type(JsonFieldType.STRING)
                    .description("message"),
                fieldWithPath("data").type(JsonFieldType.BOOLEAN)
                    .description("data")
            )
        ));
}

尝试过改用relaxedQueryParameters、requestParameters均无效，需要解决该问题。

原因分析 #

你使用RestDocumentationRequestBuilders.post()的.param()方法添加的参数是表单请求参数（request parameters），这些参数会被放在请求体中（Content-Type为application/x-www-form-urlencoded），而非URL末尾的查询参数（query parameters，即?key=value格式）。但RESTDocs配置中使用了queryParameters()来捕获参数，导致它在URL查询参数中找不到对应字段，从而抛出异常。

解决方案 #

根据你的API设计选择对应方案：

方案1：API接收表单请求参数 #

将RESTDocs配置中的queryParameters()替换为requestParameters()，因为这些参数属于表单请求参数范畴：

.andDo(document("driver-login",
    preprocessResponse(prettyPrint()),
    requestParameters( // 替换为requestParameters
        parameterWithName("driverId").description("driverId"),
        parameterWithName("password").description("password"),
        parameterWithName("loginState").description("loginState"),
        parameterWithName("deviceDiv").description("deviceDiv"),
        parameterWithName("regId").description("GCM Key")
    ),
    responseFields(
        fieldWithPath("code").type(JsonFieldType.NUMBER)
            .description("code"),
        fieldWithPath("message").type(JsonFieldType.STRING)
            .description("message"),
        fieldWithPath("data").type(JsonFieldType.BOOLEAN)
            .description("data")
    )
));

如果之前尝试requestParameters()无效，检查以下几点：

• 确认导入了正确的静态方法：import static org.springframework.restdocs.request.RequestDocumentation.requestParameters;
• 检查参数名与接口中@RequestParam的名称完全一致（大小写、拼写无错误）
• 查看andDo(print())的输出，确认参数出现在Request Parameters部分而非Query Parameters部分

方案2：API从URL查询参数获取值 #

将测试代码中的.param()替换为.queryParam()，这样参数会被添加到URL的查询参数中，同时保留RESTDocs的queryParameters()配置：

mockMvc.perform(
        RestDocumentationRequestBuilders.post("/api/driver/login")
            .queryParam("driverId", "2") // 替换为queryParam
            .queryParam("password", "2222")
            .queryParam("loginState", "1")
            .queryParam("deviceDiv", "1")
            .queryParam("regId", "please_input_gcm_code")
    )

内容的提问来源于stack exchange，提问作者Soo-Bin Kong