使用 Asciidoctor
本节描述了使用 Asciidoctor 的方面，这些方面与 Spring REST Docs 特别相关。
Asciidoc 是文档格式。
Asciidoctor 是从 Asciidoc 文件（以.adoc). |
包括 Snippets
本节介绍如何包含 Asciidoc 片段。
为一个作包含多个代码段
您可以使用名为operation导入为特定作生成的全部或部分代码段。
它通过包括spring-restdocs-asciidoctor在项目的 build configuration 中。
宏的目标是作的名称。 在最简单的形式中，您可以使用宏来包含作的所有代码片段，如以下示例所示：
operation::index[]您可以使用 operation 宏还支持snippets属性。
这snippets属性来选择应包含的代码段。
该属性的值是一个逗号分隔的列表。
列表中的每个条目都应该是一个代码段文件的名称（减去.adocsuffix） 来包含。
例如，只能包含 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[]章节标题
对于使用operationmacro 中，将创建具有标题的部分。
为以下内置代码片段提供了默认标题：
| 片段 | 标题 |
|---|---|
|
curl 请求 |
|
HTTP 请求 |
|
HTTP 响应 |
|
HTTPie 请求 |
|
链接 |
|
请求正文 |
|
请求字段 |
|
响应正文 |
|
响应字段 |
对于上表中未列出的代码段，通过将字符替换为空格并将第一个字母大写来生成默认标题。
例如，名为-custom-snippet will be“自定义代码段”。
您可以使用 document 属性自定义默认标题。
属性的名称应为operation-{snippet}-title.
例如，要自定义curl-requestsnippet 设置为 “Example request”，则可以使用以下属性：
: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 用户手册的 Tables 部分。