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.