This version is still in development and is not considered stable yet. For the latest stable version, please use Spring REST Docs 4.0.0!

Query Parameters

You can document a request’s query parameters by using queryParameters. The following examples show how to do so:

MockMvc
WebTestClient

import org.junit.jupiter.api.Test;

import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.request.RequestDocumentation.queryParameters;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

class QueryParameters {

	// Fields

	private MockMvc mockMvc;


	@Test
	void test() throws Exception {
		this.mockMvc.perform(get("/users?page=2&per_page=100")) (1)
			.andExpect(status().isOk())
			.andDo(document("users", queryParameters((2)
					parameterWithName("page").description("The page to retrieve"), (3)
					parameterWithName("per_page").description("Entries per page") (4)
			)));
	}

}

1	Perform a `GET` request with two parameters, `page` and `per_page`, in the query string. Query parameters should be included in the URL, as shown here, or specified using the request builder’s `queryParam` or `queryParams` method. The `param` and `params` methods should be avoided as the source of the parameters is then ambiguous.
2	Configure Spring REST Docs to produce a snippet describing the request’s query parameters. Uses the static `queryParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
3	Document the `page` query parameter. Uses the static `parameterWithName` method on `org.springframework.restdocs.request.RequestDocumentation`.
4	Document the `per_page` query parameter.

import org.junit.jupiter.api.Test;

import org.springframework.test.web.reactive.server.WebTestClient;

import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
import static org.springframework.restdocs.request.RequestDocumentation.queryParameters;
import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document;

class QueryParameters {

	// Fields

	private WebTestClient webTestClient;


	@Test
	void test() {
		this.webTestClient.get()
			.uri("/users?page=2&per_page=100") (1)
			.exchange()
			.expectStatus()
			.isOk()
			.expectBody()
			.consumeWith(document("users", queryParameters((2)
					parameterWithName("page").description("The page to retrieve"), (3)
					parameterWithName("per_page").description("Entries per page") (4)
			)));
	}

}

1	Perform a `GET` request with two parameters, `page` and `per_page`, in the query string.
2	Configure Spring REST Docs to produce a snippet describing the request’s query parameters. Uses the static `queryParameters` method on `org.springframework.restdocs.request.RequestDocumentation`.
3	Document the `page` parameter. Uses the static `parameterWithName` method on `org.springframework.restdocs.request.RequestDocumentation`.
4	Document the `per_page` parameter.

When documenting query parameters, the test fails if an undocumented query parameter is used in the request’s query string. Similarly, the test also fails if a documented query parameter is not found in the request’s query string and the parameter has not been marked as optional.

If you do not want to document a query parameter, you can mark it as ignored. This prevents it from appearing in the generated snippet while avoiding the failure described above.

You can also document query parameters in a relaxed mode where any undocumented parameters do not cause a test failure. To do so, use the relaxedQueryParameters method on org.springframework.restdocs.request.RequestDocumentation. This can be useful when documenting a particular scenario where you only want to focus on a subset of the query parameters.