パスパラメーター

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

  • 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.pathParameters;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

public class PathParameters {

	// Fields

	private MockMvc mockMvc;


	@Test
	void test() throws Exception {
		this.mockMvc.perform(get("/locations/{latitude}/{longitude}", 51.5072, 0.1275)) (1)
			.andExpect(status().isOk())
			.andDo(document("locations", pathParameters((2)
					parameterWithName("latitude").description("The location's latitude"), (3)
					parameterWithName("longitude").description("The location's longitude") (4)
			)));
	}

}
1latitude と longitude の 2 つのパスパラメーターを指定して GET リクエストを実行します。
2 リクエストのパスパラメーターを説明するスニペットを生成するように Spring REST Docs を設定します。org.springframework.restdocs.request.RequestDocumentation で静的 pathParameters メソッドを使用します。
3latitude という名前のパラメーターをドキュメント化します。org.springframework.restdocs.request.RequestDocumentation で静的 parameterWithName メソッドを使用します。
4longitude という名前のパラメーターをドキュメント化します。
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.pathParameters;
import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document;

class PathParameters {

	// Fields


	private WebTestClient webTestClient;


	@Test
	void test() {
		this.webTestClient.get()
			.uri("/locations/{latitude}/{longitude}", 51.5072, 0.1275) (1)
			.exchange()
			.expectStatus()
			.isOk()
			.expectBody()
			.consumeWith(document("locations", pathParameters((2)
					parameterWithName("latitude").description("The location's latitude"), (3)
					parameterWithName("longitude").description("The location's longitude")))); (4)
	}

}
1latitude と longitude の 2 つのパスパラメーターを指定して GET リクエストを実行します。
2 リクエストのパスパラメーターを説明するスニペットを生成するように Spring REST Docs を設定します。org.springframework.restdocs.request.RequestDocumentation で静的 pathParameters メソッドを使用します。
3latitude という名前のパラメーターをドキュメント化します。org.springframework.restdocs.request.RequestDocumentation で静的 parameterWithName メソッドを使用します。
4longitude という名前のパラメーターをドキュメント化します。

その結果、path-parameters.adoc という名前のスニペットが作成されます。このスニペットには、リソースでサポートされているパスパラメーターを説明するテーブルが含まれています。

パスパラメーターをドキュメント化する場合、ドキュメント化されていないパスパラメーターがリクエストで使用されていると、テストは失敗します。同様に、ドキュメント化されたパスパラメーターがリクエストに見つからず、パスパラメーターがオプションとしてマークされていない場合も、テストは失敗します。

ドキュメント化されていないパラメーターがテストの失敗を引き起こさない緩和モードで、パスパラメーターをドキュメント化することもできます。これを行うには、org.springframework.restdocs.request.RequestDocumentation で relaxedPathParameters メソッドを使用します。これは、パスパラメーターのサブセットのみに注目したい特定のシナリオをドキュメント化する場合に役立ちます。

パスパラメーターをドキュメント化したくない場合は、無視するようにマークできます。そうすることで、前述の失敗を回避しながら、生成されたスニペットに表示されなくなります。