This version is still in development and is not considered stable yet. For the latest stable version, please use Spring REST Docs 4.0.0!

HTTP Headers

You can document the headers in a request or response by using requestHeaders and responseHeaders, respectively. The following examples show how to do so:

MockMvc
WebTestClient

import org.junit.jupiter.api.Test;

import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.restdocs.headers.HeaderDocumentation.headerWithName;
import static org.springframework.restdocs.headers.HeaderDocumentation.requestHeaders;
import static org.springframework.restdocs.headers.HeaderDocumentation.responseHeaders;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

class HttpHeaders {

	// Fields

	private MockMvc mockMvc;


	@Test
	void test() throws Exception {
		this.mockMvc.perform(get("/people").header("Authorization", "Basic dXNlcjpzZWNyZXQ=")) (1)
			.andExpect(status().isOk())
			.andDo(document("headers", requestHeaders((2)
					headerWithName("Authorization").description("Basic auth credentials")), (3)
					responseHeaders((4)
							headerWithName("X-RateLimit-Limit")
								.description("The total number of requests permitted per period"),
							headerWithName("X-RateLimit-Remaining")
								.description("Remaining requests permitted in current period"),
							headerWithName("X-RateLimit-Reset")
								.description("Time at which the rate limit period will reset"))));
	}

}

1	Perform a `GET` request with an `Authorization` header that uses basic authentication.
2	Configure Spring REST Docs to produce a snippet describing the request’s headers. Uses the static `requestHeaders` method on `org.springframework.restdocs.headers.HeaderDocumentation`.
3	Document the `Authorization` header. Uses the static `headerWithName` method on `org.springframework.restdocs.headers.HeaderDocumentation`.
4	Produce a snippet describing the response’s headers. Uses the static `responseHeaders` method on `org.springframework.restdocs.headers.HeaderDocumentation`.

import org.junit.jupiter.api.Test;

import org.springframework.test.web.reactive.server.WebTestClient;

import static org.springframework.restdocs.headers.HeaderDocumentation.headerWithName;
import static org.springframework.restdocs.headers.HeaderDocumentation.requestHeaders;
import static org.springframework.restdocs.headers.HeaderDocumentation.responseHeaders;
import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document;

class HttpHeaders {

	// Fields

	private WebTestClient webTestClient;


	@Test
	void test() {
		this.webTestClient.get()
			.uri("/people")
			.header("Authorization", "Basic dXNlcjpzZWNyZXQ=") (1)
			.exchange()
			.expectStatus()
			.isOk()
			.expectBody()
			.consumeWith(document("headers", requestHeaders((2)
					headerWithName("Authorization").description("Basic auth credentials")), (3)
					responseHeaders((4)
							headerWithName("X-RateLimit-Limit")
								.description("The total number of requests permitted per period"),
							headerWithName("X-RateLimit-Remaining")
								.description("Remaining requests permitted in current period"),
							headerWithName("X-RateLimit-Reset")
								.description("Time at which the rate limit period will reset"))));
	}

}

1	Perform a `GET` request with an `Authorization` header that uses basic authentication.
2	Configure Spring REST Docs to produce a snippet describing the request’s headers. Uses the static `requestHeaders` method on `org.springframework.restdocs.headers.HeaderDocumentation`.
3	Document the `Authorization` header. Uses the static `headerWithName` method on `org.springframework.restdocs.headers.HeaderDocumentation`.
4	Produce a snippet describing the response’s headers. Uses the static `responseHeaders` method on `org.springframework.restdocs.headers.HeaderDocumentation`.

The result is a snippet named request-headers.adoc and a snippet named response-headers.adoc. Each contains a table describing the headers.

When documenting HTTP Headers, the test fails if a documented header is not found in the request or response.