使用 Asciidoctor
本节描述了与 Spring REST Docs 特别相关的 Asciidoctor 使用方面。
Asciidoc 是文档格式。
Asciidoctor 是从 Asciidoc 文件（以 .adoc 结尾）生成内容（通常为 HTML）的工具。 |
包含代码片段
本节介绍如何包含 Asciidoc 代码片段。
为操作包含多个代码片段
您可以使用名为 operation 的宏来导入为特定操作生成的全部或部分代码片段。
通过在项目的 构建配置 中包含 spring-restdocs-asciidoctor，即可使用该宏。
宏的目标是操作的名称。 在其最简单的形式中，您可以使用该宏包含某个操作的所有代码片段，如下例所示：
operation::index[]操作宏还支持 snippets 属性。
您可以使用它来选择应包含的代码片段。
该属性的值是一个逗号分隔的列表。
列表中的每个条目应为要包含的代码片段文件的名称（不含 .adoc 后缀）。
例如，可以仅包含 curl、HTTP 请求和 HTTP 响应代码片段，如下例所示：
operation::index[snippets='curl-request,http-request,http-response']前面的示例等同于以下内容：
[[example_curl_request]]
== Curl request
include::{snippets}/index/curl-request.adoc[]
[[example_http_request]]
== HTTP request
include::{snippets}/index/http-request.adoc[]
[[example_http_response]]
== HTTP response
include::{snippets}/index/http-response.adoc[]章节标题
对于每个使用 operation 宏包含的代码片段，都会创建一个带有标题的章节。
以下为内置代码片段提供的默认标题：
| 代码片段 | 标题 |
|---|---|
|
Curl 请求 |
|
HTTP 请求 |
|
HTTP 响应 |
|
HTTPie 请求 |
|
链接 |
|
请求体 |
|
请求字段 |
|
响应体 |
|
响应字段 |
对于上表中未列出的代码片段，默认标题是通过将 - 字符替换为空格并将首字母大写生成的。
例如，名为 custom-snippet will be 的代码片段的标题为“自定义代码片段”。
您可以通过使用文档属性来自定义默认标题。
属性名称应为 operation-{snippet}-title。
例如，若要将 curl-request 代码片段的标题自定义为"示例请求"，您可以使用以下属性：
:operation-curl-request-title: Example request自定义表格
许多代码片段在其默认配置中包含一个表格。 表格的外观可以进行自定义，既可以在包含代码片段时提供额外的配置，也可以使用自定义的代码片段模板。
格式化列
Asciidoctor 对格式化表格列提供了丰富的支持。
如下例所示，您可以通过使用 cols 属性来指定表格列的宽度：
[cols="1,3"] (1)
include::{snippets}/index/links.adoc[]| 1 | 表格的宽度被分配到两列中，其中第二列的宽度是第一列的三倍。 |
配置标题
您可以通过使用以 . 开头的行来指定表格的标题。
以下示例展示了如何实现这一点：
.Links (1)
include::{snippets}/index/links.adoc[]| 1 | 表格的标题将是 Links。 |
避免表格格式问题
Asciidoctor 使用 | 字符来分隔表格中的单元格。
如果您希望在单元格内容中显示 |，这可能会引发问题。
您可以通过使用反斜杠转义 | 来避免该问题——换句话说，使用 \| 而不是 |。
所有默认的 Asciidoctor 片段模板都会通过一个名为 tableCellContent 的 Mustache _lambda_ 自动执行此转义操作。
如果您编写自己的自定义模板，可能需要使用此 _lambda_。
以下示例展示了如何在包含 description 属性值的单元格中转义 | 字符：
| {{#tableCellContent}}{{description}}{{/tableCellContent}}
进一步阅读
有关自定义表格的更多信息，请参阅 Asciidoctor 用户手册的表格部分。