クエリパラメーター

queryParameters を使用すると、リクエストのクエリパラメーターをドキュメント化できます。以下の例は、その方法を示しています。

  • 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 クエリ文字列に 2 つのパラメーター page と per_page を指定して、GET リクエストを実行します。クエリパラメーターは、ここに示すように URL に含めるか、リクエストビルダーの queryParam または queryParams メソッドを使用して指定する必要があります。パラメーターのソースが曖昧になるため、param および params メソッドは使用しないでください。
2Spring REST Docs を設定して、リクエストのクエリパラメーターを記述するスニペットを生成します。org.springframework.restdocs.request.RequestDocumentation では静的メソッド queryParameters を使用します。
3Document the page query parameter. Uses the static parameterWithName method on org.springframework.restdocs.request.RequestDocumentation.
4Document 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 クエリ文字列に page と per_page の 2 つのパラメーターを指定して GET リクエストを実行します。
2Spring REST Docs を設定して、リクエストのクエリパラメーターを記述するスニペットを生成します。org.springframework.restdocs.request.RequestDocumentation では静的メソッド queryParameters を使用します。
3page パラメーターをドキュメント化します。org.springframework.restdocs.request.RequestDocumentation で静的 parameterWithName メソッドを使用します。
4per_page パラメーターをドキュメント化します。

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.