使用 Asciidoctor
本节描述了使用 Asciidoctor 的方面，这些方面与 Spring REST Docs 特别相关。
Asciidoc 是文档格式。
Asciidoctor 是从 Asciidoc 文件（以.adoc). |
包括片段
本节介绍如何包含 Asciidoc 片段。
包括用于作的多个代码段
您可以使用名为operation导入为特定作生成的全部或部分代码段。
它可以通过包括spring-restdocs-asciidoctor在项目的构建配置中。spring-restdocs-asciidoctor需要 AsciidoctorJ 3.0。
宏的目标是作的名称。 在最简单的形式中，您可以使用宏包含作的所有代码片段，如以下示例所示：
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宏，将创建一个带有标题的部分。
为以下内置代码段提供默认标题：
| 片段 | 标题 |
|---|---|
|
卷曲请求 |
|
HTTP 请求 |
|
HTTP 响应 |
|
HTTPie 请求 |
|
链接 |
|
请求正文 |
|
请求字段 |
|
响应正文 |
|
响应字段 |
对于上表中未列出的代码片段，通过将字符替换为空格并将第一个字母大写来生成默认标题。
例如，名为-custom-snippet will be“自定义代码段”。
您可以使用文档属性自定义默认标题。
属性的名称应为operation-{snippet}-title.
例如，要自定义curl-requestsnippet 设置为“示例请求”，则可以使用以下属性：
:operation-curl-request-title: Example request自定义表格
许多代码片段在其默认配置中包含一个表。 可以通过在包含代码段时提供一些其他配置或使用自定义代码段模板来自定义表的外观。
设置列格式
Asciidoctor 对表格列的格式化有丰富的支持。
如以下示例所示，您可以使用cols属性：
[cols="1,3"] (1)
include::{snippets}/index/links.adoc[]| 1 | 表格的宽度分为两列，第二列的宽度是第一列的三倍。 |
避免表格格式问题
Asciidoctor 使用|字符来分隔表中的单元格。
如果您想要|显示在单元格的内容中。
您可以通过转义|带有反斜杠——换句话说，通过使用\|而不是|.
所有默认的 Asciidoctor 代码片段模板都使用名为tableCellContent.
如果您编写自己的自定义模板，您可能需要使用此 lamba。
以下示例演示如何转义|包含description属性：
| {{#tableCellContent}}{{description}}{{/tableCellContent}}
延伸阅读
有关自定义表格的更多信息，请参阅 Asciidoctor 用户手册的表格部分。