配置 (Configuration) | Spring REST Docsversion 3.0.6-SNAPSHOT中文文档|Spring官方文档|SpringBoot 教程|Spring中文网

配置

本节介绍如何配置 Spring REST Docs。spring-doc.cadn.net.cn

记录的 URI

本节介绍配置记录的 URI。spring-doc.cadn.net.cn

MockMvc URI 自定义

使用 MockMvc 时，Spring REST Docs 记录的 URI 的默认配置如下：spring-doc.cadn.net.cn

设置默认值

设置	默认值
方案spring-doc.cadn.net.cn	`http`spring-doc.cadn.net.cn
主机spring-doc.cadn.net.cn	`localhost`spring-doc.cadn.net.cn
端口spring-doc.cadn.net.cn	`8080`spring-doc.cadn.net.cn

方案spring-doc.cadn.net.cn

httpspring-doc.cadn.net.cn

主机spring-doc.cadn.net.cn

localhostspring-doc.cadn.net.cn

端口spring-doc.cadn.net.cn

8080spring-doc.cadn.net.cn

此配置由MockMvcRestDocumentationConfigurer. 您可以使用其 API 更改一个或多个默认值以满足您的需求。以下示例显示了如何执行此作：spring-doc.cadn.net.cn

this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
	.apply(documentationConfiguration(this.restDocumentation).uris()
		.withScheme("https")
		.withHost("example.com")
		.withPort(443))
	.build();

如果端口设置为配置方案的默认值（HTTP 的端口 80 或 HTTPS 的端口 443），则生成的代码片段中的任何 URI 中都会省略它。

要配置请求的上下文路径，请使用contextPath方法MockHttpServletRequestBuilder.

REST 保证 URI 自定义

REST Assured 通过发出实际的 HTTP 请求来测试服务。因此，URI 必须是在对服务执行作后但在执行之前进行自定义记录。特定于 REST 的为此目的提供了预处理器。spring-doc.cadn.net.cn

WebTestClient URI 自定义

使用 WebTestClient 时，Spring REST Docs 记录的 URI 的默认基础是http://localhost:8080. 您可以使用 baseUrl(String)方法WebTestClient.Builder. 以下示例显示了如何执行此作：spring-doc.cadn.net.cn

@Before
public void setUp() {
	this.webTestClient = WebTestClient.bindToApplicationContext(this.context)
		.configureClient()
		.baseUrl("https://api.example.com") (1)
		.filter(documentationConfiguration(this.restDocumentation))
		.build();
}

1	将记录的 URI 的基数配置为`https://api.example.com`.

片段编码

默认代码段编码为UTF-8. 您可以使用RestDocumentationConfigurer应用程序接口。例如，以下示例使用ISO-8859-1:spring-doc.cadn.net.cn

模拟视频

this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
	.apply(documentationConfiguration(this.restDocumentation).snippets().withEncoding("ISO-8859-1"))
	.build();

Web测试客户端

this.webTestClient = WebTestClient.bindToApplicationContext(this.context).configureClient()
	.filter(documentationConfiguration(this.restDocumentation)
		.snippets().withEncoding("ISO-8859-1"))
	.build();

放心

this.spec = new RequestSpecBuilder()
	.addFilter(documentationConfiguration(this.restDocumentation).snippets().withEncoding("ISO-8859-1"))
	.build();

当 Spring REST Docs 将请求或响应的内容转换为String这charset在Content-Type如果可用，则使用标头。如果没有它，JVM 的默认值Charset被使用。您可以配置 JVM 的默认Charset通过使用file.encoding系统属性。

代码片段模板格式

默认代码片段模板格式为 Asciidoctor。 Markdown 也支持开箱即用。您可以使用RestDocumentationConfigurer应用程序接口。以下示例显示了如何执行此作：spring-doc.cadn.net.cn

模拟视频

this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
	.apply(documentationConfiguration(this.restDocumentation).snippets()
		.withTemplateFormat(TemplateFormats.markdown()))
	.build();

Web测试客户端

this.webTestClient = WebTestClient.bindToApplicationContext(this.context).configureClient()
	.filter(documentationConfiguration(this.restDocumentation)
		.snippets().withTemplateFormat(TemplateFormats.markdown()))
	.build();

放心

this.spec = new RequestSpecBuilder()
	.addFilter(documentationConfiguration(this.restDocumentation).snippets()
		.withTemplateFormat(TemplateFormats.markdown()))
	.build();

默认片段

默认情况下生成六个代码段：spring-doc.cadn.net.cn

curl-requestspring-doc.cadn.net.cn
http-requestspring-doc.cadn.net.cn
http-responsespring-doc.cadn.net.cn
httpie-requestspring-doc.cadn.net.cn
request-bodyspring-doc.cadn.net.cn
response-bodyspring-doc.cadn.net.cn

您可以在设置过程中使用RestDocumentationConfigurer应用程序接口。以下示例仅生成curl-request代码段：spring-doc.cadn.net.cn

模拟视频

this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
	.apply(documentationConfiguration(this.restDocumentation).snippets().withDefaults(curlRequest()))
	.build();

Web测试客户端

this.webTestClient = WebTestClient.bindToApplicationContext(this.context)
	.configureClient().filter(
		documentationConfiguration(this.restDocumentation)
			.snippets().withDefaults(curlRequest()))
	.build();

放心

this.spec = new RequestSpecBuilder()
	.addFilter(documentationConfiguration(this.restDocumentation).snippets().withDefaults(curlRequest()))
	.build();

默认作预处理器

您可以在设置期间使用RestDocumentationConfigurer应用程序接口。以下示例删除了Foo标头，并漂亮地打印所有响应：spring-doc.cadn.net.cn

模拟视频

this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
	.apply(documentationConfiguration(this.restDocumentation).operationPreprocessors()
		.withRequestDefaults(modifyHeaders().remove("Foo")) (1)
		.withResponseDefaults(prettyPrint())) (2)
	.build();

1	应用请求预处理器，删除名为`Foo`.
2	应用一个响应预处理器来漂亮地打印其内容。

Web测试客户端

this.webTestClient = WebTestClient.bindToApplicationContext(this.context)
	.configureClient()
	.filter(documentationConfiguration(this.restDocumentation)
		.operationPreprocessors()
			.withRequestDefaults(modifyHeaders().remove("Foo")) (1)
			.withResponseDefaults(prettyPrint())) (2)
	.build();

1	应用请求预处理器，删除名为`Foo`.
2	应用一个响应预处理器来漂亮地打印其内容。

放心

this.spec = new RequestSpecBuilder()
	.addFilter(documentationConfiguration(this.restDocumentation).operationPreprocessors()
		.withRequestDefaults(modifyHeaders().remove("Foo")) (1)
		.withResponseDefaults(prettyPrint())) (2)
	.build();

1	应用请求预处理器，删除名为`Foo`.
2	应用一个响应预处理器来漂亮地打印其内容。