リクエストとレスポンスのカスタマイズ

送信されたとおりのリクエストや、受信されたとおりのレスポンスをドキュメント化したくない場合があります。Spring REST Docs は、ドキュメント化される前にリクエストまたはレスポンスを変更するために使用できる多数のプリプロセッサーを提供します。

前処理は、OperationRequestPreprocessor または OperationResponsePreprocessor で document を呼び出すことによって構成されます。Preprocessors で静的 preprocessRequest および preprocessResponse メソッドを使用してインスタンスを取得できます。次の例は、その方法を示しています。

  • 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.operation.preprocess.Preprocessors.modifyHeaders;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessRequest;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessResponse;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

class PerTestPreprocessing {

	// Fields

	private MockMvc mockMvc;


	@Test
	void test() throws Exception {
		this.mockMvc.perform(get("/"))
			.andExpect(status().isOk())
			.andDo(document("index", preprocessRequest(modifyHeaders().remove("Foo")), (1)
					preprocessResponse(prettyPrint()))); (2)
	}

}
1Foo という名前のヘッダーを削除するリクエストプリプロセッサーを適用します。
2 コンテンツをきれいに出力するレスポンスプリプロセッサーを適用します。
import org.junit.jupiter.api.Test;

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

import static org.springframework.restdocs.operation.preprocess.Preprocessors.modifyHeaders;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessRequest;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessResponse;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;
import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document;

class PerTestPreprocessing {

	// Fields

	private WebTestClient webTestClient;


	@Test
	void test() {
		this.webTestClient.get()
			.uri("/")
			.exchange()
			.expectStatus()
			.isOk()
			.expectBody()
			.consumeWith(document("index", preprocessRequest(modifyHeaders().remove("Foo")), (1)
					preprocessResponse(prettyPrint()))); (2)
	}

}
1Foo という名前のヘッダーを削除するリクエストプリプロセッサーを適用します。
2 コンテンツをきれいに出力するレスポンスプリプロセッサーを適用します。

または、すべてのテストに同じプリプロセッサーを適用することもできます。これを行うには、@BeforeEach メソッドで RestDocumentationConfigurer API を使用してプリプロセッサーを構成します。例: すべてのリクエストから Foo ヘッダーを削除し、すべてのレスポンスをきれいに出力するには、次のいずれかを実行できます (テスト環境によって異なります)。

  • MockMvc

  • WebTestClient

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.extension.ExtendWith;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.restdocs.RestDocumentationContextProvider;
import org.springframework.restdocs.RestDocumentationExtension;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.modifyHeaders;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;

@ExtendWith(RestDocumentationExtension.class)
public class EveryTestPreprocessing {

	// Fields

	@Autowired
	private WebApplicationContext context;

	private MockMvc mockMvc;


	@BeforeEach
	void setUp(RestDocumentationContextProvider restDocumentation) {
		this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
			.apply(documentationConfiguration(restDocumentation).operationPreprocessors()
				.withRequestDefaults(modifyHeaders().remove("Foo")) (1)
				.withResponseDefaults(prettyPrint())) (2)
			.build();
	}

}
1Foo という名前のヘッダーを削除するリクエストプリプロセッサーを適用します。
2 コンテンツをきれいに出力するレスポンスプリプロセッサーを適用します。
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.extension.ExtendWith;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.ApplicationContext;
import org.springframework.restdocs.RestDocumentationContextProvider;
import org.springframework.restdocs.RestDocumentationExtension;
import org.springframework.test.web.reactive.server.WebTestClient;

import static org.springframework.restdocs.operation.preprocess.Preprocessors.modifyHeaders;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;
import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.documentationConfiguration;

@ExtendWith(RestDocumentationExtension.class)
class EveryTestPreprocessing {

	// Fields

	@Autowired
	private ApplicationContext context;

	private WebTestClient webTestClient;


	@BeforeEach
	void setUp(RestDocumentationContextProvider restDocumentation) {
		this.webTestClient = WebTestClient.bindToApplicationContext(this.context)
			.configureClient()
			.filter(documentationConfiguration(restDocumentation).operationPreprocessors()
				.withRequestDefaults(modifyHeaders().remove("Foo")) (1)
				.withResponseDefaults(prettyPrint())) (2)
			.build();
	}

}
1Foo という名前のヘッダーを削除するリクエストプリプロセッサーを適用します。
2 コンテンツをきれいに出力するレスポンスプリプロセッサーを適用します。

上に示したものを含むさまざまな組み込みプリプロセッサーは、Preprocessors の静的メソッドを通じて利用できます。詳細については、以下を参照してください。

プリプロセッサー

プリティー印刷

 Preprocessors 上の prettyPrint は、リクエストまたはレスポンスの内容をフォーマットして、読みやすくします。

ハイパーメディアベースの API をドキュメント化する場合、ハードコーディングされた URI を使用するのではなく、リンクを使用して API をナビゲートするようにクライアントに勧めることができます。そのための 1 つの方法は、ドキュメントでの URI の使用を制限することです。Preprocessors 上の maskLinks は、レスポンス内のすべてのリンクの href を …​ に置き換えます。必要に応じて、別の置換を指定することもできます。

ヘッダーの変更

Preprocessors で modifyHeaders を使用して、リクエストヘッダーまたはレスポンスヘッダーを追加、設定、削除できます。

パターンの置き換え

 Preprocessors 上の replacePattern は、リクエストまたはレスポンスのコンテンツを置き換えるための汎用メカニズムを提供します。正規表現に一致する出現箇所はすべて置き換えられます。

URI の変更

サーバーにバインドされていない MockMvc または WebTestClient を使用する場合は、構成を変更して URI をカスタマイズする必要があります。

Preprocessors で modifyUris を使用すると、リクエストまたはレスポンス内の任意の URI を変更できます。サーバーにバインドされた WebTestClient を使用する場合、サービスのローカルインスタンスをテストする際に、ドキュメントに表示される URI をカスタマイズできます。

独自のプリプロセッサーを作成する

組み込みのプリプロセッサーの 1 つがニーズを満たさない場合は、OperationPreprocessor インターフェースを実装することで独自のプリプロセッサーを作成できます。その後、任意の組み込みプリプロセッサーとまったく同じ方法でカスタムプリプロセッサーを使用できます。

リクエストまたはレスポンスのコンテンツ (本文) のみを変更する場合は、ContentModifier インターフェースを実装し、それを組み込みの ContentModifyingOperationPreprocessor と共に使用することを検討してください。