出力のカスタマイズ

生成されたスニペットのカスタマイズ

Spring REST Docs は Mustache (英語) テンプレートを使用して、生成されたスニペットを生成します。デフォルトテンプレート [GitHub] (英語) は、Spring REST Docs が生成できるスニペットごとに提供されます。スニペットのコンテンツをカスタマイズするために、独自のテンプレートを提供できます。

テンプレートは、org.springframework.restdocs.templates サブパッケージのクラスパスからロードされます。サブパッケージの名前は、使用中のテンプレート形式の ID によって決まります。デフォルトのテンプレート形式 Asciidoctor の ID は asciidoctor であるため、スニペットは org.springframework.restdocs.templates.asciidoctor からロードされます。各テンプレートは、それが生成するスニペットにちなんで名付けられています。例: curl-request.adoc スニペットのテンプレートをオーバーライドするには、src/test/resources/org/springframework/restdocs/templates/asciidoctor に curl-request.snippet という名前のテンプレートを作成します。

追加情報を含む

生成されたスニペットに含める追加情報を提供するには、次の 2 つの方法があります。

  • 記述子で attributes メソッドを使用して、1 つ以上の属性を追加します。

  • curlRequest、httpRequest、httpResponse などを呼び出すときに、いくつかの属性を渡します。このような属性は、スニペット全体に関連付けられています。

追加の属性は、テンプレートのレンダリングプロセス中に使用可能になります。カスタムスニペットテンプレートと組み合わせると、生成されたスニペットに追加情報を含めることができます。

具体的な例は、リクエストフィールドをドキュメント化する際の制約列とタイトルの追加です。最初のステップは、ドキュメント化する各フィールドに constraints 属性を提供し、title 属性を提供することです。次の例は、その方法を示しています。

  • MockMvc

  • WebTestClient

import org.junit.jupiter.api.Test;

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

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.post;
import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.requestFields;
import static org.springframework.restdocs.snippet.Attributes.attributes;
import static org.springframework.restdocs.snippet.Attributes.key;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

class IncludingExtraInformation {

	// Fields

	private MockMvc mockMvc;


	@Test
	void test() throws Exception {
		this.mockMvc.perform(post("/users/").accept(MediaType.APPLICATION_JSON))
			.andExpect(status().isOk())
			.andDo(document("create-user", requestFields(attributes(key("title").value("Fields for user creation")), (1)
					fieldWithPath("name").description("The user's name")
						.attributes(key("constraints").value("Must not be null. Must not be empty")), (2)
					fieldWithPath("email").description("The user's email address")
						.attributes(key("constraints").value("Must be a valid email address"))))); (3)
	}

}
1 リクエストフィールドスニペットの title 属性を設定します。
2name フィールドの constraints 属性を設定します。
3email フィールドの constraints 属性を設定します。
import org.junit.jupiter.api.Test;

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

import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.requestFields;
import static org.springframework.restdocs.snippet.Attributes.attributes;
import static org.springframework.restdocs.snippet.Attributes.key;
import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document;

class IncludingExtraInformation {

	// Fields

	private WebTestClient webTestClient;


	@Test
	void test() {
		this.webTestClient.get()
			.uri("user/5")
			.accept(MediaType.APPLICATION_JSON)
			.exchange()
			.expectStatus()
			.isOk()
			.expectBody()
			.consumeWith(document("create-user",
					requestFields(attributes(key("title").value("Fields for user creation")), (1)
							fieldWithPath("name").description("The user's name")
								.attributes(key("constraints").value("Must not be null. Must not be empty")), (2)
							fieldWithPath("email").description("The user's email address")
								.attributes(key("constraints").value("Must be a valid email address"))))); (3)
	}

}
1 リクエストフィールドスニペットの title 属性を設定します。
2name フィールドの constraints 属性を設定します。
3email フィールドの constraints 属性を設定します。

2 番目のステップは、生成されたスニペットのテーブル内のフィールドの制約に関する情報を含め、タイトルを追加する、request-fields.snippet という名前のカスタムテンプレートを提供することです。

.{{title}} (1)
|===
|Path|Type|Description|Constraints (2)

{{#fields}}
|{{path}}
|{{type}}
|{{description}}
|{{constraints}} (3)

{{/fields}}
|===