使用 Asciidoctor

本节描述了使用 Asciidoctor 的方面,这些方面与 Spring REST Docs 特别相关。spring-doc.cn

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

包括 Snippets

本节介绍如何包含 Asciidoc 片段。spring-doc.cn

为一个操作包含多个代码段

您可以使用 named 的宏来导入为特定操作生成的全部或部分代码段。 它可以通过包含在项目的生成配置中来使用。operationspring-restdocs-asciidoctorspring-doc.cn

宏的目标是操作的名称。 在最简单的形式中,您可以使用宏来包含操作的所有代码片段,如以下示例所示:spring-doc.cn

operation::index[]

您可以使用 operation 宏也支持属性。 用于选择应包含的代码段的属性。 该属性的值是一个逗号分隔的列表。 列表中的每个条目都应该是要包含的代码段文件的名称(不包括后缀)。 例如,只能包含 curl、HTTP 请求和 HTTP 响应代码段,如以下示例所示:snippetssnippets.adocspring-doc.cn

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

前面的示例等效于以下内容:spring-doc.cn

[[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[]
章节标题

对于使用宏包含的每个代码段,将创建一个带有标题的章节。 为以下内置代码片段提供了默认标题:operationspring-doc.cn

片段 标题

curl-requestspring-doc.cn

curl 请求spring-doc.cn

http-requestspring-doc.cn

HTTP 请求spring-doc.cn

http-responsespring-doc.cn

HTTP 响应spring-doc.cn

httpie-requestspring-doc.cn

HTTPie 请求spring-doc.cn

linksspring-doc.cn

链接spring-doc.cn

request-bodyspring-doc.cn

请求正文spring-doc.cn

request-fieldsspring-doc.cn

请求字段spring-doc.cn

response-bodyspring-doc.cn

响应正文spring-doc.cn

response-fieldsspring-doc.cn

响应字段spring-doc.cn

对于上表中未列出的代码段,通过将字符替换为空格并将第一个字母大写来生成默认标题。 例如,名为“Custom snippet”的代码段的标题。-custom-snippetwill bespring-doc.cn

您可以使用 document 属性自定义默认标题。 属性的名称应为 。 例如,要将代码段的标题自定义为“Example request”,您可以使用以下属性:operation-{snippet}-titlecurl-requestspring-doc.cn

:operation-curl-request-title: Example request

包括单个代码段

include 宏用于在文档中包含单个代码段。 您可以使用该属性(通过在构建配置中配置自动设置)来引用 snippets 输出目录。 以下示例显示了如何执行此操作:snippetsspring-restdocs-asciidoctorspring-doc.cn

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

自定义表

许多代码段在其默认配置中包含一个表。 可以自定义表的外观,方法是在包含代码段时提供一些其他配置,或者使用自定义代码段模板。spring-doc.cn

设置列格式

Asciidoctor 对格式化表格的列有丰富的支持。 如下例所示,您可以使用以下属性指定表列的宽度:colsspring-doc.cn

[cols="1,3"] (1)
include::{snippets}/index/links.adoc[]
1 表格的宽度被拆分为两列,第二列的宽度是第一列的三倍。

配置标题

您可以使用前缀为 . 以下示例显示了如何执行此操作:.spring-doc.cn

.Links (1)
include::{snippets}/index/links.adoc[]
1 表的标题将为 。Links

避免表格格式问题

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

所有默认的 Asciidoctor 代码段模板都使用名为 的 Mustache lamba 自动执行此转义。 如果您编写自己的自定义模板,则可能需要使用此 lamba。 下面的示例演示如何对包含属性值的单元格中的字符进行转义:tableCellContent|descriptionspring-doc.cn

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

延伸阅读

有关自定义表的更多信息,请参阅 Asciidoctor 用户手册的 Tables 部分spring-doc.cn