[[configuration]]
== Configuration



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



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

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

|===
|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:

[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 will be 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`. This base can be customized using the
{spring-framework-api}/org/springframework/test/web/reactive/server/WebTestClient.Builder.html#baseUrl-java.lang.String-[
`baseUrl(String)` method on `WebTestClient.Builder`]:

[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
using the `RestDocumentationConfigurer` API. For example, to 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 a request or response's content to a String, the
`charset` specified in the `Content-Type` header will be used if it is available. In its
absence, the JVM's default `Charset` will be used. The JVM's default `Charset` can be
configured using 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 using the `RestDocumentationConfigurer` API:

[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 using the
`RestDocumentationConfigurer` API. For example, to only produce 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 using the
`RestDocumentationConfigurer` API. For example, to 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 will remove the header named `Foo`.
<2> Apply a response preprocessor that will pretty print 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 will remove the header named `Foo`.
<2> Apply a response preprocessor that will pretty print 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 will remove the header named `Foo`.
<2> Apply a response preprocessor that will pretty print its content.

