配置 (Configuration) _ Spring REST Docsversion 3.0.3中文文档(官方文档中文翻译)|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 都会省略该端口。

要配置请求的上下文路径，请使用contextPathmethod 开启MockHttpServletRequestBuilder.

REST Assured URI 自定义

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

WebTestClient URI 自定义

当使用 WebTestClient 时，Spring REST Docs 记录的 URI 的默认基础是http://localhost:8080. 您可以使用 baseUrl(String)method 开启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

MockMvc

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

WebTest客户端

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如果可用，则使用 header。如果没有它，JVM 的默认Charset被使用。您可以配置 JVM 的默认值Charset通过使用file.encodingsystem 属性。

代码段模板格式

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

MockMvc

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

WebTest客户端

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();

默认代码段

默认情况下，会生成 6 个代码段：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-requestsnippet 中：spring-doc.cadn.net.cn

MockMvc

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

WebTest客户端

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应用程序接口。以下示例删除Fooheaders 和 pretty print 所有响应：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	应用一个响应预处理器，该预处理器可以漂亮地打印其内容。

WebTest客户端

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	应用一个响应预处理器，该预处理器可以漂亮地打印其内容。