Spring REST Docs文档（二）

自定义请求和响应

在某些情况下，您可能不希望完全按照发送的方式记录请求或完全按照收到的响应记录响应。 Spring REST Docs 提供了许多预处理器，可用于在记录请求或响应之前对其进行修改。

预处理是通过使用 或 . 您可以使用 上的 static 和 方法来获取实例。 以下示例演示如何执行此操作：​​document​​​​OperationRequestPreprocessor​​​​OperationResponsePreprocessor​​​​preprocessRequest​​​​preprocessResponse​​​​Preprocessors​​

this.mockMvc.perform(get("/")).andExpect(status().isOk()) .andDo(document("index", preprocessRequest(modifyHeaders().remove("Foo")), preprocessResponse(prettyPrint())));

应用请求预处理器，删除名为 的标头。​​Foo​​

应用一个响应预处理器，漂亮地打印其内容。

或者，您可能希望对每个测试应用相同的预处理器。 为此，可以在方法中使用 API 来配置预处理器。 例如，要从所有请求中删除标头并漂亮地打印所有响应，您可以执行以下操作之一（取决于您的测试环境）：​​RestDocumentationConfigurer​​​​@Before​​​​Foo​​

private MockMvc mockMvc;@Beforepublic void setup() { this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context) .apply(documentationConfiguration(this.restDocumentation).operationPreprocessors() .withRequestDefaults(modifyHeaders().remove("Foo")) .withResponseDefaults(prettyPrint())) .build();}

应用请求预处理器，删除名为 的标头。​​Foo​​

应用一个响应预处理器，漂亮地打印其内容。

然后，在每个测试中，您可以执行特定于该测试的任何配置。 以下示例演示如何执行此操作：

this.mockMvc.perform(get("/")).andExpect(status().isOk()) .andDo(document("index", links(linkWithRel("self").description("Canonical self link"))));

各种内置预处理器（包括上图所示的预处理器）可通过 上的静态方法获得。 有关更多详细信息，请参见下文。​​Preprocessors​​

预处理器

漂亮的印刷

​​prettyPrint​​on 设置请求或响应内容的格式，使其更易于阅读。​​Preprocessors​​

屏蔽链接

如果要记录基于超媒体的 API，则可能需要鼓励客户端使用链接而不是使用硬编码 URI 来导航 API。 一种方法是在文档中限制 URI 的使用。 on 将响应中任何链接的 替换为 。 如果需要，还可以指定其他替换。​​maskLinks​​​​Preprocessors​​​​href​​​​…​​

修改标头

可以使用 on 添加、设置和删除请求或响应标头。​​modifyHeaders​​​​Preprocessors​​

替换模式

​​replacePattern​​on 提供用于替换请求或响应中内容的通用机制。 与正则表达式匹配的任何匹配项都将被替换。​​Preprocessors​​

修改 URI

如果您使用 MockMvc 或未绑定到服务器的 WebTestClient，则应通过更改配置来自定义 URI。

可以使用 on 修改请求或响应中的任何 URI。 使用绑定到服务器的 REST Assured 或 WebTestClient 时，这允许您在测试服务的本地实例时自定义文档中显示的 URI。modifyUrisPreprocessors

编写自己的预处理器

如果其中一个内置预处理器不能满足您的需求，您可以通过实现接口来编写自己的预处理器。 然后，您可以像使用任何内置预处理器完全相同的方式使用自定义预处理器。​​OperationPreprocessor​​

如果只想修改请求或响应的内容（正文），请考虑实现接口并将其与内置 .​​ContentModifier​​​​ContentModifyingOperationPreprocessor​​

配置

本节介绍如何配置 Spring REST 文档。

记录的 URI

本节介绍如何配置记录的 URI。

模拟Mvc URI定制

使用 MockMvc 时，Spring REST Docs 记录的 URI 的默认配置如下：

设置

违约

方案

​​http​​

主机

​​localhost​​

港口

​​8080​​

此配置由 应用。 您可以使用其 API 更改一个或多个默认值以满足您的需求。 以下示例演示如何执行此操作：​​MockMvcRestDocumentationConfigurer​​

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​​

放心 URI 定制

REST Assured 通过发出实际的 HTTP 请求来测试服务。因此，URI 必须 在对服务执行操作后但在执行操作之前自定义 记录。特定于 REST 保证 为此提供了预处理器。

网络测试客户端 URI 自定义

使用 WebTestClient 时，Spring REST Docs 记录的 URI 的默认基础是 。 您可以通过在 WebTestClient.Builder 上使用 baseUrl（String） 方法自定义此基库。 以下示例演示如何执行此操作：​​http://localhost:8080​​

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

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

代码段编码

默认代码段编码为 。 您可以使用 API 更改默认代码段编码。 例如，以下示例使用：​​UTF-8​​​​RestDocumentationConfigurer​​​​ISO-8859-1​

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

当 Spring REST 文档将请求或响应的内容转换为 时，如果可用，则使用标头中指定的内容。 如果没有它，则使用 JVM 的缺省值。 您可以使用系统属性配置 JVM 的缺省值。​​String​​​​charset​​​​Content-Type​​​​Charset​​​​Charset​​​​file.encoding​​

代码段模板格式

默认代码段模板格式为 Asciidoctor。 开箱即用也支持降价。 您可以使用 API 更改默认格式。 以下示例演示如何执行此操作：​​RestDocumentationConfigurer​​

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

默认代码段

默认情况下会生成六个代码段：

• ​​curl-request​​
• ​​http-request​​
• ​​http-response​​
• ​​httpie-request​​
• ​​request-body​​
• ​​response-body​​

您可以在安装过程中使用 API 更改默认代码段配置。 默认情况下，以下示例仅生成代码段：​​RestDocumentationConfigurer​​​​curl-request​​

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

默认操作预处理器

您可以在安装过程中使用 API 配置默认请求和响应预处理器。 以下示例从所有请求中删除标头并漂亮地打印所有响应：​​RestDocumentationConfigurer​​​​Foo​​

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

应用请求预处理器，删除名为 的标头。​​Foo​​

应用一个响应预处理器，漂亮地打印其内容。

与阿斯凯医生合作

本节描述了使用 Asciidoctor 与 Spring REST 文档特别相关的方面。

Asciidoc 是文档格式。 Asciidoctor是从Asciidoc文件（以 结尾）生成内容（通常为 HTML）的工具。​​.adoc​​

资源

• 语法快速参考
• 用户手册

包括代码段

本节介绍如何包含 Asciidoc 代码段。

包括操作的多个代码段

您可以使用名为的宏导入为特定操作生成的全部或部分代码段。 它通过包含在项目的生成配置中来提供。​​operation​​​​spring-restdocs-asciidoctor​​

宏的目标是操作的名称。 在最简单的形式中，可以使用宏包含操作的所有代码段，如以下示例所示：

operation::index[]

可以使用操作宏也支持属性。 用于选择应包含的代码段的属性。 属性的值是以逗号分隔的列表。 列表中的每个条目都应是要包含的代码段文件的名称（减去后缀）。 例如，只能包含 curl、HTTP 请求和 HTTP 响应代码段，如以下示例所示：​​snippets​​​​snippets​​​​.adoc​​

operation::index[snippets='curl-request,http-request,http-response']

前面的示例等效于以下内容：

[[example_curl_request]]== Curl requestinclude::{snippets}/index/curl-request.adoc[][[example_http_request]]== HTTP requestinclude::{snippets}/index/http-request.adoc[][[example_http_response]]== HTTP responseinclude::{snippets}/index/http-response.adoc[]

章节标题

对于使用宏包含的每个代码段，将创建一个带有标题的部分。 为以下内置代码段提供了默认标题：​​operation​​

片段

标题

​​curl-request​​

卷曲请求

​​http-request​​

HTTP请求

​​http-response​​

HTTP响应

​​httpie-request​​

HTTPie 请求

​​links​​

链接

​​request-body​​

请求正文

​​request-fields​​

请求字段

​​response-body​​

响应正文

​​response-fields​​

响应字段

对于上表中未列出的代码段，将通过用空格替换字符并将第一个字母大写来生成默认标题。 例如，名为“自定义代码段”的代码段的标题。​​-​​​​custom-snippet​​​​will be​​

您可以使用文档属性自定义默认标题。 属性的名称应为 。 例如，要将代码段的标题自定义为“示例请求”，您可以使用以下属性：​​operation-{snippet}-title​​​​curl-request​​

:operation-curl-request-title: Example request

包括单个代码段

包含宏用于在文档中包含各个代码段。 您可以使用该属性（由在构建配置中配置自动设置）来引用代码段输出目录。 以下示例演示如何执行此操作：​​snippets​​​​spring-restdocs-asciidoctor​​

include::{snippets}/index/curl-request.adoc[]

定制表格

许多代码段在其默认配置中包含表。 可以通过在包含代码段时提供一些其他配置或使用自定义代码段模板来自定义表的外观。

设置列的格式

Asciidoctor对格式化表格的列提供了丰富的支持。 如以下示例所示，您可以使用该属性指定表列的宽度：​​cols​​

[cols="1,3"] include::{snippets}/index/links.adoc[]

表格的宽度分为两列，第二列的宽度是第一列的三倍。

配置标题

可以使用以 为前缀的行指定表的标题。 以下示例演示如何执行此操作：​​.​​

.Links include::{snippets}/index/links.adoc[]

表的标题将为 。​​Links​​

避免表格格式问题

Asciidoctor使用该字符分隔表中的单元格。 如果您希望 显示在单元格的内容中，这可能会导致问题。 您可以通过使用反斜杠转义来避免此问题 — 换句话说，通过使用而不是 .​​|​​​​|​​​​|​​​​\|​​​​|​​

所有默认的 Asciidoctor 代码段模板都使用名为 的胡子兰巴自动执行此转义。 如果您编写自己的自定义模板，则可能需要使用此 lamba。 下面的示例演示如何在包含属性值的单元格中转义字符：​​tableCellContent​​​​|​​​​description​​

| {{#tableCellContent}}{{description}}{{/tableCellContent}}

延伸阅读

有关自定义表格的更多信息，请参阅 Asciidoctor 用户手册的表格部分。

使用 Markdown

本节描述了使用 Markdown 与 Spring REST 文档特别相关的方面。

局限性

Markdown最初是为为网络写作的人设计的，因此并不像Asciidoctor那样适合编写文档。 通常，通过使用另一个构建在 Markdown 之上的工具来克服这些限制。

Markdown没有官方对表格的支持。 Spring REST Docs的默认Markdown代码段模板使用Markdown Extra的表格格式。

包括代码段

Markdown 没有内置支持将一个 Markdown 文件包含在另一个文件中。 要在文档中包含生成的 Markdown 代码段，您应该使用支持此功能的附加工具。 一个特别适合记录 API 的示例是 Slate。

贡献

Spring REST Docs 旨在让您轻松地为 RESTful 服务生成高质量的文档。 但是，没有你们的贡献，我们就无法实现这一目标。

问题

您可以使用标签在堆栈溢出上询问有关Spring REST Docs的问题。 同样，我们鼓励您通过回答问题来帮助您的Spring REST Docs用户。spring-restdocs

错误

如果您认为发现了错误，请花点时间搜索现有问题。 如果没有其他人报告该问题，请打开一个新问题，详细描述该问题，理想情况下，包括重现该问题的测试。

增强

如果你想对Spring REST Docs进行增强，非常欢迎拉取请求。 源代码在GitHub上。 您可能需要搜索现有问题和拉取请求，以查看是否已提出增强功能。 您可能还想打开一个新问题，以便在开始处理之前讨论可能的增强功能。

【转自：香港服务器 https://www.68idc.cn提供,感谢支持】