Merge pull request #592 from clydebarrow

* gh-592:
  Polish "Add support for documenting request and response cookies"
  Add support for documenting request and response cookies

Closes gh-592

Author: wilkinsona

config/checkstyle/checkstyle.xml

@@ -5,7 +5,8 @@
 		<property name="file" value="${config_loc}/checkstyle-suppressions.xml"/>
 	</module>
 	<module name="io.spring.javaformat.checkstyle.SpringChecks">
-		<property name="avoidStaticImportExcludes" value=" org.springframework.restdocs.cli.CliDocumentation.*"/>
+		<property name="avoidStaticImportExcludes" value="org.springframework.restdocs.cli.CliDocumentation.*,
+				org.springframework.restdocs.cookies.CookieDocumentation.*"/>
 	</module>
 	<module name="com.puppycrawl.tools.checkstyle.TreeWalker">
 		<module name="com.puppycrawl.tools.checkstyle.checks.imports.IllegalImportCheck">

docs/build.gradle

@@ -21,6 +21,7 @@ dependencies {
 	testImplementation(project(":spring-restdocs-mockmvc"))
 	testImplementation(project(":spring-restdocs-restassured"))
 	testImplementation(project(":spring-restdocs-webtestclient"))
+	testImplementation("jakarta.servlet:jakarta.servlet-api")
 	testImplementation("jakarta.validation:jakarta.validation-api")
 	testImplementation("junit:junit")
 	testImplementation("org.testng:testng:6.9.10")

docs/src/docs/asciidoc/documenting-your-api.adoc

@@ -989,6 +989,58 @@ When documenting HTTP Headers, the test fails if a documented header is not foun
 
 
 
+[[documenting-your-api-http-cookies]]
+=== 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:
+
+[source,java,indent=0,role="primary"]
+.MockMvc
+----
+include::{examples-dir}/com/example/mockmvc/HttpCookies.java[tags=cookies]
+----
+<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`.
+
+[source,java,indent=0,role="secondary"]
+.WebTestClient
+----
+include::{examples-dir}/com/example/webtestclient/HttpCookies.java[tags=cookies]
+----
+<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`.
+
+[source,java,indent=0,role="secondary"]
+.REST Assured
+----
+include::{examples-dir}/com/example/restassured/HttpCookies.java[tags=cookies]
+----
+<1> Configure Spring REST Docs to produce a snippet describing the request's cookies.
+	Uses the static `requestCookies` method on `org.springframework.restdocs.cookies.CookieDocumentation`.
+<2> Document the `JSESSIONID` cookie.
+	Uses the static `cookieWithName` method on `org.springframework.restdocs.cookies.CookieDocumentation`.
+<3> Produce a snippet describing the response's cookies.
+	Uses the static `responseCookies` method on `org.springframework.restdocs.cookies.CookieDocumentation`.
+<4> Send a `JSESSIONID` cookie with the request.
+
+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 a documented cookie is not found in the request or response.
+
+
+
 [[documenting-your-api-reusing-snippets]]
 === Reusing Snippets
 

docs/src/test/java/com/example/mockmvc/HttpCookies.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2014-2022 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.mockmvc;
+
+import jakarta.servlet.http.Cookie;
+
+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;
+
+public class HttpCookies {
+
+	private MockMvc mockMvc;
+
+	public void cookies() throws Exception {
+		// tag::cookies[]
+		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"))));
+		// end::cookies[]
+	}
+
+}

docs/src/test/java/com/example/restassured/HttpCookies.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2014-2022 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.restassured;
+
+import io.restassured.RestAssured;
+import io.restassured.specification.RequestSpecification;
+
+import static org.hamcrest.CoreMatchers.is;
+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.restassured.RestAssuredRestDocumentation.document;
+
+public class HttpCookies {
+
+	private RequestSpecification spec;
+
+	public void cookies() {
+		// tag::cookies[]
+		RestAssured.given(this.spec).filter(document("cookies", requestCookies(// <1>
+				cookieWithName("JSESSIONID").description("Saved session token")), // <2>
+				responseCookies(// <3>
+						cookieWithName("logged_in").description("If user is logged in"),
+						cookieWithName("JSESSIONID").description("Updated session token"))))
+				.cookie("JSESSIONID", "ACBCDFD0FF93D5BB") // <4>
+				.when().get("/people").then().assertThat().statusCode(is(200));
+		// end::cookies[]
+	}
+
+}

docs/src/test/java/com/example/webtestclient/HttpCookies.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2014-2022 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.webtestclient;
+
+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;
+
+public class HttpCookies {
+
+	private WebTestClient webTestClient;
+
+	public void cookies() {
+		// tag::cookies[]
+		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"))));
+		// end::cookies[]
+	}
+
+}

spring-restdocs-core/src/main/java/org/springframework/restdocs/cookies/AbstractCookiesSnippet.java

@@ -0,0 +1,158 @@
+/*
+ * Copyright 2014-2022 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.restdocs.cookies;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Map.Entry;
+import java.util.Set;
+
+import org.springframework.restdocs.operation.Operation;
+import org.springframework.restdocs.snippet.TemplatedSnippet;
+import org.springframework.util.Assert;
+
+/**
+ * Abstract {@link TemplatedSnippet} subclass that provides a base for snippets that
+ * document a RESTful resource's request or response cookies.
+ *
+ * @author Clyde Stubbs
+ * @author Andy Wilkinson
+ * @since 3.0
+ */
+public abstract class AbstractCookiesSnippet extends TemplatedSnippet {
+
+	private final Map<String, CookieDescriptor> descriptorsByName = new LinkedHashMap<>();
+
+	private final boolean ignoreUndocumentedCookies;
+
+	/**
+	 * Creates a new {@code AbstractCookiesSnippet} that will produce a snippet named
+	 * {@code <type>-cookies}. The cookies will be documented using the given
+	 * {@code  descriptors} and the given {@code attributes} will be included in the model
+	 * during template rendering.
+	 * @param type the type of the cookies
+	 * @param descriptors the cookie descriptors
+	 * @param attributes the additional attributes
+	 * @param ignoreUndocumentedCookies whether undocumented cookies should be ignored
+	 */
+	protected AbstractCookiesSnippet(String type, List<CookieDescriptor> descriptors, Map<String, Object> attributes,
+			boolean ignoreUndocumentedCookies) {
+		super(type + "-cookies", attributes);
+		for (CookieDescriptor descriptor : descriptors) {
+			Assert.notNull(descriptor.getName(), "Cookie descriptors must have a name");
+			if (!descriptor.isIgnored()) {
+				Assert.notNull(descriptor.getDescription(), "The descriptor for cookie '" + descriptor.getName()
+						+ "' must either have a description or be marked as ignored");
+			}
+			this.descriptorsByName.put(descriptor.getName(), descriptor);
+		}
+		this.ignoreUndocumentedCookies = ignoreUndocumentedCookies;
+	}
+
+	@Override
+	protected Map<String, Object> createModel(Operation operation) {
+		verifyCookieDescriptors(operation);
+
+		Map<String, Object> model = new HashMap<>();
+		List<Map<String, Object>> cookies = new ArrayList<>();
+		for (CookieDescriptor descriptor : this.descriptorsByName.values()) {
+			if (!descriptor.isIgnored()) {
+				cookies.add(createModelForDescriptor(descriptor));
+			}
+		}
+		model.put("cookies", cookies);
+		return model;
+	}
+
+	private void verifyCookieDescriptors(Operation operation) {
+		Set<String> actualCookies = extractActualCookies(operation);
+		Set<String> expectedCookies = new HashSet<>();
+		for (Entry<String, CookieDescriptor> entry : this.descriptorsByName.entrySet()) {
+			if (!entry.getValue().isOptional()) {
+				expectedCookies.add(entry.getKey());
+			}
+		}
+		Set<String> undocumentedCookies;
+		if (this.ignoreUndocumentedCookies) {
+			undocumentedCookies = Collections.emptySet();
+		}
+		else {
+			undocumentedCookies = new HashSet<>(actualCookies);
+			undocumentedCookies.removeAll(this.descriptorsByName.keySet());
+		}
+		Set<String> missingCookies = new HashSet<>(expectedCookies);
+		missingCookies.removeAll(actualCookies);
+
+		if (!undocumentedCookies.isEmpty() || !missingCookies.isEmpty()) {
+			verificationFailed(undocumentedCookies, missingCookies);
+		}
+	}
+
+	/**
+	 * Extracts the names of the cookies from the request or response of the given
+	 * {@code operation}.
+	 * @param operation the operation
+	 * @return the cookie names
+	 */
+	protected abstract Set<String> extractActualCookies(Operation operation);
+
+	/**
+	 * Called when the documented cookies do not match the actual cookies.
+	 * @param undocumentedCookies the cookies that were found in the operation but were
+	 * not documented
+	 * @param missingCookies the cookies that were documented but were not found in the
+	 * operation
+	 */
+	protected abstract void verificationFailed(Set<String> undocumentedCookies, Set<String> missingCookies);
+
+	/**
+	 * Returns the list of {@link CookieDescriptor CookieDescriptors} that will be used to
+	 * generate the documentation.
+	 * @return the cookie descriptors
+	 */
+	protected final Map<String, CookieDescriptor> getCookieDescriptors() {
+		return this.descriptorsByName;
+	}
+
+	/**
+	 * Returns whether or not this snippet ignores undocumented cookies.
+	 * @return {@code true} if undocumented cookies are ignored, otherwise {@code false}
+	 */
+	protected final boolean isIgnoreUndocumentedCookies() {
+		return this.ignoreUndocumentedCookies;
+	}
+
+	/**
+	 * Returns a model for the given {@code descriptor}.
+	 * @param descriptor the descriptor
+	 * @return the model
+	 */
+	protected Map<String, Object> createModelForDescriptor(CookieDescriptor descriptor) {
+		Map<String, Object> model = new HashMap<>();
+		model.put("name", descriptor.getName());
+		model.put("description", descriptor.getDescription());
+		model.put("optional", descriptor.isOptional());
+		model.putAll(descriptor.getAttributes());
+		return model;
+	}
+
+}