配置

本节介绍如何配置 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

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 中都会省略该端口。
要配置请求的上下文路径，请在 MockHttpServletRequestBuilder 上使用 contextPath 方法。

REST Assured URI 自定义

REST Assured 通过发起真实的 HTTP 请求来测试服务。因此，必须在对服务执行操作之后、但在生成文档之前自定义 URI。为此，提供了一个 REST-Assured 专用的预处理器。spring-doc.cadn.net.cn

WebTestClient URI 自定义

使用 WebTestClient 时，Spring REST Docs 记录的 URI 默认基址为 http://localhost:8080。 您可以通过在 WebTestClient.Builder 上使用 baseUrl(String) 方法 来自定义此基址。 以下示例展示了如何实现：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 API 更改默认代码片段编码。 例如，以下示例使用了 ISO-8859-1：spring-doc.cadn.net.cn

MockMvc
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
	.apply(documentationConfiguration(this.restDocumentation).snippets().withEncoding("ISO-8859-1"))
	.build();
WebTestClient
this.webTestClient = WebTestClient.bindToApplicationContext(this.context).configureClient()
	.filter(documentationConfiguration(this.restDocumentation)
		.snippets().withEncoding("ISO-8859-1"))
	.build();
REST Assured
this.spec = new RequestSpecBuilder()
	.addFilter(documentationConfiguration(this.restDocumentation).snippets().withEncoding("ISO-8859-1"))
	.build();
当 Spring REST Docs 将请求或响应的内容转换为 String 时，如果 Content-Type 标头中指定的 charset 可用，则会使用该编码。 如果不可用，则使用 JVM 的默认 Charset。 您可以通过使用 file.encoding 系统属性来配置 JVM 的默认 Charset。

代码片段模板格式

默认的片段模板格式是 Asciidoctor。 Markdown 也开箱即用。 您可以使用 RestDocumentationConfigurer API 更改默认格式。 以下示例展示了如何操作：spring-doc.cadn.net.cn

MockMvc
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
	.apply(documentationConfiguration(this.restDocumentation).snippets()
		.withTemplateFormat(TemplateFormats.markdown()))
	.build();
WebTestClient
this.webTestClient = WebTestClient.bindToApplicationContext(this.context).configureClient()
	.filter(documentationConfiguration(this.restDocumentation)
		.snippets().withTemplateFormat(TemplateFormats.markdown()))
	.build();
REST Assured
this.spec = new RequestSpecBuilder()
	.addFilter(documentationConfiguration(this.restDocumentation).snippets()
		.withTemplateFormat(TemplateFormats.markdown()))
	.build();

默认代码片段

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

您可以在安装过程中使用 RestDocumentationConfigurer API 更改默认代码片段配置。 以下示例默认仅生成 curl-request 代码片段：spring-doc.cadn.net.cn

MockMvc
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
	.apply(documentationConfiguration(this.restDocumentation).snippets().withDefaults(curlRequest()))
	.build();
WebTestClient
this.webTestClient = WebTestClient.bindToApplicationContext(this.context)
	.configureClient().filter(
		documentationConfiguration(this.restDocumentation)
			.snippets().withDefaults(curlRequest()))
	.build();
REST Assured
this.spec = new RequestSpecBuilder()
	.addFilter(documentationConfiguration(this.restDocumentation).snippets().withDefaults(curlRequest()))
	.build();

默认操作预处理器

您可以在设置期间使用 RestDocumentationConfigurer API 配置默认的请求和响应预处理器。 以下示例将从所有请求中移除 Foo 头，并对所有响应进行美化打印：spring-doc.cadn.net.cn

MockMvc
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
	.apply(documentationConfiguration(this.restDocumentation).operationPreprocessors()
		.withRequestDefaults(modifyHeaders().remove("Foo")) (1)
		.withResponseDefaults(prettyPrint())) (2)
	.build();
1 应用一个请求预处理器，移除名为 Foo 的请求头。
2 应用一个响应预处理器，以美化其内容输出。
WebTestClient
this.webTestClient = WebTestClient.bindToApplicationContext(this.context)
	.configureClient()
	.filter(documentationConfiguration(this.restDocumentation)
		.operationPreprocessors()
			.withRequestDefaults(modifyHeaders().remove("Foo")) (1)
			.withResponseDefaults(prettyPrint())) (2)
	.build();
1 应用一个请求预处理器，移除名为 Foo 的请求头。
2 应用一个响应预处理器，以美化其内容输出。
REST Assured
this.spec = new RequestSpecBuilder()
	.addFilter(documentationConfiguration(this.restDocumentation).operationPreprocessors()
		.withRequestDefaults(modifyHeaders().remove("Foo")) (1)
		.withResponseDefaults(prettyPrint())) (2)
	.build();
1 应用一个请求预处理器，移除名为 Foo 的请求头。
2 应用一个响应预处理器，以美化其内容输出。