[[configuration]]
== Configuration

This section covers how to configure Spring REST Docs.

[[configuration-uris]]
=== Documented URIs

This section covers configuring documented URIs.

[[configuration-uris-mockmvc]]
==== MockMvc URI Customization

When using MockMvc, the default configuration for URIs documented by Spring REST Docs is
as follows:

|===
|Setting |Default

|Scheme
|`http`

|Host
|`localhost`

|Port
|`8080`
|===

This configuration is applied by `MockMvcRestDocumentationConfigurer`. You can use its
API to change one or more of the defaults to suit your needs. The following example shows
how to do so:

====
[source,java,indent=0]
----
include::{examples-dir}/com/example/mockmvc/CustomUriConfiguration.java[tags=custom-uri-configuration]
----
====

NOTE: If the port is set to the default for the configured scheme (port 80 for HTTP or
port 443 for HTTPS), it is omitted from any URIs in the generated snippets.

TIP: To configure a request's context path, use the `contextPath` method on
`MockHttpServletRequestBuilder`.



[[configuration-uris-rest-assured]]
==== REST Assured URI Customization

REST Assured tests a service by making actual HTTP requests. As a result, URIs must be
customized once the operation on the service has been performed but before it is
documented. A
<<customizing-requests-and-responses-preprocessors-modify-uris, REST-Assured-specific
preprocessor>> is provided for this purpose.



[[configuration-uris-webtestclient]]
==== WebTestClient URI Customization

When using WebTestClient, the default base for URIs documented by Spring REST
Docs is `http://localhost:8080`. You can customize this base by using the
{spring-framework-api}/org/springframework/test/web/reactive/server/WebTestClient.Builder.html#baseUrl-java.lang.String-[
`baseUrl(String)` method on `WebTestClient.Builder`]. The following example shows how to
do so:

====
[source,java,indent=0]
----
include::{examples-dir}/com/example/webtestclient/CustomUriConfiguration.java[tags=custom-uri-configuration]
----
<1> Configure the base of documented URIs to be `https://api.example.com`.
====



[[configuration-snippet-encoding]]
=== 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`:

====
[source,java,indent=0,role="primary"]
.MockMvc
----
include::{examples-dir}/com/example/mockmvc/CustomEncoding.java[tags=custom-encoding]
----

[source,java,indent=0,role="secondary"]
.WebTestClient
----
include::{examples-dir}/com/example/webtestclient/CustomEncoding.java[tags=custom-encoding]
----

[source,java,indent=0,role="secondary"]
.REST Assured
----
include::{examples-dir}/com/example/restassured/CustomEncoding.java[tags=custom-encoding]
----
====

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



[[configuration-snippet-template-format]]
=== 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:

====
[source,java,indent=0,role="primary"]
.MockMvc
----
include::{examples-dir}/com/example/mockmvc/CustomFormat.java[tags=custom-format]
----

[source,java,indent=0,role="secondary"]
.WebTestClient
----
include::{examples-dir}/com/example/webtestclient/CustomFormat.java[tags=custom-format]
----

[source,java,indent=0,role="secondary"]
.REST Assured
----
include::{examples-dir}/com/example/restassured/CustomFormat.java[tags=custom-format]
----
====



[[configuration-default-snippets]]
=== 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:

====
[source,java,indent=0,role="primary"]
.MockMvc
----
include::{examples-dir}/com/example/mockmvc/CustomDefaultSnippets.java[tags=custom-default-snippets]
----

[source,java,indent=0,role="secondary"]
.WebTestClient
----
include::{examples-dir}/com/example/webtestclient/CustomDefaultSnippets.java[tags=custom-default-snippets]
----

[source,java,indent=0,role="secondary"]
.REST Assured
----
include::{examples-dir}/com/example/restassured/CustomDefaultSnippets.java[tags=custom-default-snippets]
----
====

[[configuration-default-preprocessors]]
=== 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:

====
[source,java,indent=0,role="primary"]
.MockMvc
----
include::{examples-dir}/com/example/mockmvc/CustomDefaultOperationPreprocessors.java[tags=custom-default-operation-preprocessors]
----
<1> Apply a request preprocessor that removes the header named `Foo`.
<2> Apply a response preprocessor that pretty prints its content.

[source,java,indent=0,role="secondary"]
.WebTestClient
----
include::{examples-dir}/com/example/webtestclient/CustomDefaultOperationPreprocessors.java[tags=custom-default-operation-preprocessors]
----
<1> Apply a request preprocessor that removes the header named `Foo`.
<2> Apply a response preprocessor that pretty prints its content.

[source,java,indent=0,role="secondary"]
.REST Assured
----
include::{examples-dir}/com/example/restassured/CustomDefaultOperationPreprocessors.java[tags=custom-default-operation-preprocessors]
----
<1> Apply a request preprocessor that removes the header named `Foo`.
<2> Apply a response preprocessor that pretty prints its content.
====
