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.