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 Cookies

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

MockMvc
WebTestClient

import jakarta.servlet.http.Cookie;
import org.junit.jupiter.api.Test;

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

import static org.springframework.restdocs.cookies.CookieDocumentation.cookieWithName;
import static org.springframework.restdocs.cookies.CookieDocumentation.requestCookies;
import static org.springframework.restdocs.cookies.CookieDocumentation.responseCookies;
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 HttpCookies {

	// Fields

	private MockMvc mockMvc;


	@Test
	void test() throws Exception {
		this.mockMvc.perform(get("/").cookie(new Cookie("JSESSIONID", "ACBCDFD0FF93D5BB"))) (1)
			.andExpect(status().isOk())
			.andDo(document("cookies", requestCookies((2)
					cookieWithName("JSESSIONID").description("Session token")), (3)
					responseCookies((4)
							cookieWithName("JSESSIONID").description("Updated session token"),
							cookieWithName("logged_in")
								.description("Set to true if the user is currently logged in"))));
	}

}

1	Make a GET request with a `JSESSIONID` cookie.
2	Configure Spring REST Docs to produce a snippet describing the request’s cookies. Uses the static `requestCookies` method on `org.springframework.restdocs.cookies.CookieDocumentation`.
3	Document the `JSESSIONID` cookie. Uses the static `cookieWithName` method on `org.springframework.restdocs.cookies.CookieDocumentation`.
4	Produce a snippet describing the response’s cookies. Uses the static `responseCookies` method on `org.springframework.restdocs.cookies.CookieDocumentation`.

import org.junit.jupiter.api.Test;

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

import static org.springframework.restdocs.cookies.CookieDocumentation.cookieWithName;
import static org.springframework.restdocs.cookies.CookieDocumentation.requestCookies;
import static org.springframework.restdocs.cookies.CookieDocumentation.responseCookies;
import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document;

class HttpCookies {

	// Fields

	private WebTestClient webTestClient;


	@Test
	void test() {
		this.webTestClient.get()
			.uri("/people")
			.cookie("JSESSIONID", "ACBCDFD0FF93D5BB=") (1)
			.exchange()
			.expectStatus()
			.isOk()
			.expectBody()
			.consumeWith(document("cookies", requestCookies((2)
					cookieWithName("JSESSIONID").description("Session token")), (3)
					responseCookies((4)
							cookieWithName("JSESSIONID").description("Updated session token"),
							cookieWithName("logged_in").description("User is logged in"))));
	}

}

1	Make a GET request with a `JSESSIONID` cookie.
2	Configure Spring REST Docs to produce a snippet describing the request’s cookies. Uses the static `requestCookies` method on `org.springframework.restdocs.cookies.CookieDocumentation`.
3	Document the `JSESSIONID` cookie. Uses the static `cookieWithName` method on `org.springframework.restdocs.cookies.CookieDocumentation`.
4	Produce a snippet describing the response’s cookies. Uses the static `responseCookies` method on `org.springframework.restdocs.cookies.CookieDocumentation`.

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

When documenting HTTP cookies, the test fails if an undocumented cookie is found in the request or response. Similarly, the test also fails if a documented cookie is not found and the cookie has not been marked as optional. You can also document cookies in a relaxed mode, where any undocumented cookies do not cause a test failure. To do so, use the relaxedRequestCookies and relaxedResponseCookies methods on org.springframework.restdocs.cookies.CookieDocumentation. This can be useful when documenting a particular scenario where you only want to focus on a subset of the cookies. If you do not want to document a cookie, you can mark it as ignored. Doing so prevents it from appearing in the generated snippet while avoiding the failure described earlier.