使用 Asciidoctor
本节描述了使用 Asciidoctor 的方面,这些方面与 Spring REST Docs 特别相关。
Asciidoc 是文档格式。
Asciidoctor 是从 Asciidoc 文件(以 结尾)生成内容(通常为 HTML)的工具。.adoc |
包括 Snippets
本节介绍如何包含 Asciidoc 片段。
为一个操作包含多个代码段
您可以使用 named 的宏来导入为特定操作生成的全部或部分代码段。
它可以通过包含在项目的生成配置中来使用。operation
spring-restdocs-asciidoctor
宏的目标是操作的名称。 在最简单的形式中,您可以使用宏来包含操作的所有代码片段,如以下示例所示:
operation::index[]
您可以使用 operation 宏也支持属性。
用于选择应包含的代码段的属性。
该属性的值是一个逗号分隔的列表。
列表中的每个条目都应该是要包含的代码段文件的名称(不包括后缀)。
例如,只能包含 curl、HTTP 请求和 HTTP 响应代码段,如以下示例所示:snippets
snippets
.adoc
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”的代码段的标题。-
custom-snippet
will be
您可以使用 document 属性自定义默认标题。
属性的名称应为 。
例如,要将代码段的标题自定义为“Example request”,您可以使用以下属性:operation-{snippet}-title
curl-request
:operation-curl-request-title: Example request
自定义表
许多代码段在其默认配置中包含一个表。 可以自定义表的外观,方法是在包含代码段时提供一些其他配置,或者使用自定义代码段模板。
设置列格式
Asciidoctor 对格式化表格的列有丰富的支持。
如下例所示,您可以使用以下属性指定表列的宽度:cols
[cols="1,3"] (1)
include::{snippets}/index/links.adoc[]
1 | 表格的宽度被拆分为两列,第二列的宽度是第一列的三倍。 |
避免表格格式问题
Asciidoctor 使用该字符来分隔表中的单元格。
如果您希望 a 显示在单元格的内容中,这可能会导致问题。
您可以通过使用反斜杠转义 the 来避免这个问题 — 换句话说,通过使用而不是 .|
|
|
\|
|
所有默认的 Asciidoctor 代码段模板都使用名为 的 Mustache lamba 自动执行此转义。
如果您编写自己的自定义模板,则可能需要使用此 lamba。
下面的示例演示如何对包含属性值的单元格中的字符进行转义:tableCellContent
|
description
| {{#tableCellContent}}{{description}}{{/tableCellContent}}
延伸阅读
有关自定义表的更多信息,请参阅 Asciidoctor 用户手册的 Tables 部分。