Spring REST Docs 05.07.

2021, 21:57

(https://docs.spring.io/spring-framework/docs/5.0.x/javadoc-
api/org/springframework/test/web/reactive/server/WebTestClient.Builder.html#baseUrl-java.lang.String-)
. The following example shows how to do so:

JAVA
@@BBeeffo rree
ppuubblli cc v ooiid s eettU pp() {
tthhi ss.webTestClient = WebTestClient.bindToApplicationContext(tth i ss.context)
.configureClient()
.baseUrl("https://api.example.com") 1
.filter(documentationConfiguration(tthhi ss.restDocumentation)).build();
}

1 Configure the base of documented URIs to be https://api.example.com .

Snippet Encoding
The default snippet encoding is UTF-8 . You can change the default snippet encoding by using the
RestDocumentationConfigurer API. For example, the following examples use ISO-8859-1 :

MockMvc WebTestClient REST Assured

JAVA
tthhiiss.mockMvc = MockMvcBuilders.webAppContextSetup(tth i ss.context)
.apply(documentationConfiguration(tth i ss.restDocumentation)
.snippets().withEncoding("ISO-8859-1"))
.build();

When Spring REST Docs converts the content of a request or a response to a String , the
charset specified in the Content-Type header is used if it is available. In its absence, the
! JVM’s default Charset is used. You can configure the JVM’s default Charset byusing the
file.encoding system property.

Snippet Template Format

The default snippet template format is Asciidoctor. Markdown is also supported out of the box. You can change
the default format by using the RestDocumentationConfigurer API. The following examples show how to do
so:

MockMvc WebTestClient REST Assured

JAVA
tthhiiss.mockMvc = MockMvcBuilders.webAppContextSetup(tth i ss.context)
.apply(documentationConfiguration(tth i ss.restDocumentation)
.snippets().withTemplateFormat(TemplateFormats.markdown()))
.build();

https://docs.spring.io/spring-restdocs/docs/2.0.5.RELEASE/reference/html5/ Page 40 of 47
Spring REST Docs 05.07.2021, 21:57

Default Snippets
Six snippets are produced by default:

curl-request

http-request

http-response

httpie-request

request-body

response-body

You can change the default snippet configuration during setup by using the RestDocumentationConfigurer
API. The following examples produce only the curl-request snippet by default:

MockMvc WebTestClient REST Assured

JAVA
tthhiiss.mockMvc = MockMvcBuilders.webAppContextSetup(tth i ss.context)
.apply(documentationConfiguration(tth i ss.restDocumentation).snippets()
.withDefaults(curlRequest()))
.build();

Default Operation Preprocessors

You can configure default request and response preprocessors during setup by using the
RestDocumentationConfigurer API. The following examples remove the Foo headers from all requests and
pretty print all responses:

MockMvc WebTestClient REST Assured

JAVA
tthhiiss.mockMvc = MockMvcBuilders.webAppContextSetup(tth i ss.context)
.apply(documentationConfiguration(tth i ss.restDocumentation)
.operationPreprocessors()
.withRequestDefaults(removeHeaders("Foo")) 1
.withResponseDefaults(prettyPrint())) 2
.build();

1 Apply a request preprocessor that removes the header named Foo .

2 Apply a response preprocessor that pretty prints its content.

https://docs.spring.io/spring-restdocs/docs/2.0.5.RELEASE/reference/html5/ Page 41 of 47
Spring REST Docs 05.07.2021, 21:57

Working with Asciidoctor

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

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

Resources
Syntax quick reference (https://asciidoctor.org/docs/asciidoc-syntax-quick-reference)

User manual (https://asciidoctor.org/docs/user-manual)

Including Snippets
This section covers how to include Asciidoc snippets.

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.

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:

ooppeerra ttiio nn::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:

ooppeerra ttiio nn::index[snippets='curl-request,http-request,http-response']

The preceding example is the equivalent of the following:

https://docs.spring.io/spring-restdocs/docs/2.0.5.RELEASE/reference/html5/ Page 42 of 47
Spring REST Docs 05.07.2021, 21:57

ADOC
[[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:

Snippet Title

curl-request Curl Request

http-request HTTP request

http-response HTTP response

httpie-request HTTPie request

links Links

request-body Request body

request-fields Request fields

response-body Response body

response-fields Response fields

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”.

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:

https://docs.spring.io/spring-restdocs/docs/2.0.5.RELEASE/reference/html5/ Page 43 of 47
Spring REST Docs 05.07.2021, 21:57

:operation-curl-request-title: Example request

Including Individual Snippets

The include macro (https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files) 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:

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.

Formatting Columns
Asciidoctor has rich support for formatting a table’s columns (https://asciidoctor.org/docs/user-manual/#cols-format). As
the following example shows, you can specify the widths of a table’s columns by using the cols attribute:

[cols="1,3"] 1
iinnccllu ddee: ::{{s nniip ppe t s }}//i nnd e xx/ l iin k ss. a d o cc[[]

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

Con!guring 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:

.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 | .

https://docs.spring.io/spring-restdocs/docs/2.0.5.RELEASE/reference/html5/ Page 44 of 47