Working with Asciidoctor (Working with Asciidoctor) _ Spring REST Docsversion 3.0.3中文文档(官方文档中文翻译)|Spring 教程 —

Working with Asciidoctor

This section describes the aspects of working with Asciidoctor that are particularly relevant to Spring REST Docs.spring-doc.cn

Asciidoc is the document format. Asciidoctor is the tool that produces content (usually as HTML) from Asciidoc files (which end with .adoc).

Including Snippets

This section covers how to include Asciidoc snippets.spring-doc.cn

Including Multiple Snippets for an Operation

You can use a macro named operation to import all or some of the snippets that have been generated for a specific operation. It is made available by including spring-restdocs-asciidoctor in your project’s build configuration.spring-doc.cn

The target of the macro is the name of the operation. In its simplest form, you can use the macro to include all of the snippets for an operation, as shown in the following example:spring-doc.cn

operation::index[]

You can use the operation macro also supports a snippets attribute. The snippets attribute to select the snippets that should be included. The attribute’s value is a comma-separated list. Each entry in the list should be the name of a snippet file (minus the .adoc suffix) to include. For example, only the curl, HTTP request, and HTTP response snippets can be included, as shown in the following example:spring-doc.cn

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

The preceding example is the equivalent of the following: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[]

Section Titles

For each snippet that is included by using the operation macro, a section with a title is created. Default titles are provided for the following built-in snippets:spring-doc.cn

Snippet Title

Snippet	Title
`curl-request`spring-doc.cn	Curl Requestspring-doc.cn
`http-request`spring-doc.cn	HTTP requestspring-doc.cn
`http-response`spring-doc.cn	HTTP responsespring-doc.cn
`httpie-request`spring-doc.cn	HTTPie requestspring-doc.cn
`links`spring-doc.cn	Linksspring-doc.cn
`request-body`spring-doc.cn	Request bodyspring-doc.cn
`request-fields`spring-doc.cn	Request fieldsspring-doc.cn
`response-body`spring-doc.cn	Response bodyspring-doc.cn
`response-fields`spring-doc.cn	Response fieldsspring-doc.cn

curl-requestspring-doc.cn

Curl Requestspring-doc.cn

http-requestspring-doc.cn

HTTP requestspring-doc.cn

http-responsespring-doc.cn

HTTP responsespring-doc.cn

httpie-requestspring-doc.cn

HTTPie requestspring-doc.cn

linksspring-doc.cn

Linksspring-doc.cn

request-bodyspring-doc.cn

Request bodyspring-doc.cn

request-fieldsspring-doc.cn

Request fieldsspring-doc.cn

response-bodyspring-doc.cn

Response bodyspring-doc.cn

response-fieldsspring-doc.cn

Response fieldsspring-doc.cn

For snippets not listed in the preceding table, a default title is generated by replacing - characters with spaces and capitalizing the first letter. For example, the title for a snippet named custom-snippet will be “Custom snippet”.spring-doc.cn

You can customize the default titles by using document attributes. The name of the attribute should be operation-{snippet}-title. For example, to customize the title of the curl-request snippet to be "Example request", you can use the following attribute:spring-doc.cn

:operation-curl-request-title: Example request

Including Individual Snippets

The include macro is used to include individual snippets in your documentation. You can use the snippets attribute (which is automatically set by spring-restdocs-asciidoctor configured in the build configuration) to reference the snippets output directory. The following example shows how to do so:spring-doc.cn

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

Customizing Tables

Many of the snippets contain a table in its default configuration. The appearance of the table can be customized, either by providing some additional configuration when the snippet is included or by using a custom snippet template.spring-doc.cn

Formatting Columns

Asciidoctor has rich support for formatting a table’s columns. As the following example shows, you can specify the widths of a table’s columns by using the cols attribute:spring-doc.cn

[cols="1,3"] (1)
include::{snippets}/index/links.adoc[]

1	The table’s width is split across its two columns, with the second column being three times as wide as the first.

Configuring the Title

You can specify the title of a table by using a line prefixed by a .. The following example shows how to do so:spring-doc.cn

.Links (1)
include::{snippets}/index/links.adoc[]

1	The table’s title will be `Links`.

Avoiding Table Formatting Problems

Asciidoctor uses the | character to delimit cells in a table. This can cause problems if you want a | to appear in a cell’s contents. You can avoid the problem by escaping the | with a backslash — in other words, by using \| rather than |.spring-doc.cn

All of the default Asciidoctor snippet templates perform this escaping automatically by using a Mustache lamba named tableCellContent. If you write your own custom templates you may want to use this lamba. The following example shows how to escape | characters in a cell that contains the value of a description attribute:spring-doc.cn

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