Polish contribution that added support for documenting HTTP headers

The main changes are:

- Update javadoc to align with changes made in 5a01016
- Update documentation with details of the new support for documenting
  HTTP headers
- Add tests to verify that HTTP headers are matched case-insensitively

Closes gh-71

spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/AbstractHeadersSnippet.java

@@ -91,8 +91,8 @@ public abstract class AbstractHeadersSnippet extends TemplatedSnippet {
 	}
 
 	/**
-	 * Finds the headers that are missing from the operation. A header is missing if
-	 * it is described by one of the {@code headerDescriptors} but is not present in the
+	 * Finds the headers that are missing from the operation. A header is missing if it is
+	 * described by one of the {@code headerDescriptors} but is not present in the
 	 * operation.
 	 *
 	 * @param operation the operation
@@ -100,9 +100,10 @@ public abstract class AbstractHeadersSnippet extends TemplatedSnippet {
 	 */
 	protected List<HeaderDescriptor> findMissingHeaders(Operation operation) {
 		List<HeaderDescriptor> missingHeaders = new ArrayList<HeaderDescriptor>();
+		Set<String> actualHeaders = extractActualHeaders(operation);
 		for (HeaderDescriptor headerDescriptor : this.headerDescriptors) {
 			if (!headerDescriptor.isOptional()
-					&& !getHeaders(operation).contains(headerDescriptor.getName())) {
+					&& !actualHeaders.contains(headerDescriptor.getName())) {
 				missingHeaders.add(headerDescriptor);
 			}
 		}
@@ -111,13 +112,13 @@ public abstract class AbstractHeadersSnippet extends TemplatedSnippet {
 	}
 
 	/**
-	 * Returns the headers of the request or response extracted form the given
+	 * Extracts the names of the headers from the request or response of the given
 	 * {@code operation}.
 	 *
-	 * @param operation The operation
-	 * @return The headers
+	 * @param operation the operation
+	 * @return the header names
 	 */
-	protected abstract Set<String> getHeaders(Operation operation);
+	protected abstract Set<String> extractActualHeaders(Operation operation);
 
 	/**
 	 * Returns the list of {@link HeaderDescriptor HeaderDescriptors} that will be used to

spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/HeaderDescriptor.java

@@ -56,7 +56,7 @@ public class HeaderDescriptor extends AbstractDescriptor<HeaderDescriptor> {
 	 *
 	 * @return the header name
 	 */
-	public String getName() {
+	public final String getName() {
 		return this.name;
 	}
 

spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/HeaderDocumentation.java

@@ -25,6 +25,7 @@ import org.springframework.restdocs.snippet.Snippet;
  * Static factory methods for documenting a RESTful API's request and response headers.
  *
  * @author Andreas Evers
+ * @author Andy Wilkinson
  */
 public abstract class HeaderDocumentation {
 
@@ -44,15 +45,14 @@ public abstract class HeaderDocumentation {
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet documenting the headers of the API
-	 * call's request.
+	 * Returns a new {@link Snippet} that will document the headers of the API operation's
+	 * request. The headers will be documented using the given {@code descriptors}.
 	 * <p>
 	 * If a header is documented, is not marked as optional, and is not present in the
-	 * request, a failure will occur. If a header is present in the request, but is not
-	 * documented by one of the descriptors, there will be no failure.
+	 * request, a failure will occur.
 	 *
-	 * @param descriptors The descriptions of the request's headers
-	 * @return the handler
+	 * @param descriptors the descriptions of the request's headers
+	 * @return the snippet that will document the request headers
 	 * @see #headerWithName(String)
 	 */
 	public static Snippet requestHeaders(HeaderDescriptor... descriptors) {
@@ -60,17 +60,16 @@ public abstract class HeaderDocumentation {
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet documenting the headers of the API
-	 * call's request. The given {@code attributes} will be available during snippet
-	 * generation.
+	 * Returns a new {@link Snippet} that will document the headers of the API
+	 * operations's request. The given {@code attributes} will be available during snippet
+	 * generation and the headers will be documented using the given {@code descriptors}.
 	 * <p>
 	 * If a header is documented, is not marked as optional, and is not present in the
-	 * request, a failure will occur. If a header is present in the request, but is not
-	 * documented by one of the descriptors, there will be no failure.
+	 * request, a failure will occur.
 	 *
-	 * @param attributes Attributes made available during rendering of the snippet
-	 * @param descriptors The descriptions of the request's headers
-	 * @return the handler
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the request's headers
+	 * @return the snippet that will document the request headers
 	 * @see #headerWithName(String)
 	 */
 	public static Snippet requestHeaders(Map<String, Object> attributes,
@@ -79,15 +78,14 @@ public abstract class HeaderDocumentation {
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet documenting the headers of the API
-	 * call's response.
+	 * Returns a new {@link Snippet} that will document the headers of the API operation's
+	 * response. The headers will be documented using the given {@code descriptors}.
 	 * <p>
 	 * If a header is documented, is not marked as optional, and is not present in the
-	 * response, a failure will occur. If a header is present in the response, but is not
-	 * documented by one of the descriptors, there will be no failure.
+	 * request, a failure will occur.
 	 *
-	 * @param descriptors The descriptions of the response's headers
-	 * @return the handler
+	 * @param descriptors the descriptions of the response's headers
+	 * @return the snippet that will document the response headers
 	 * @see #headerWithName(String)
 	 */
 	public static Snippet responseHeaders(HeaderDescriptor... descriptors) {
@@ -95,17 +93,17 @@ public abstract class HeaderDocumentation {
 	}
 
 	/**
-	 * Returns a handler that will produce a snippet documenting the headers of the API
-	 * call's response. The given {@code attributes} will be available during snippet
-	 * generation.
+	 * Returns a new {@link Snippet} that will document the headers of the API
+	 * operations's response. The given {@code attributes} will be available during
+	 * snippet generation and the headers will be documented using the given
+	 * {@code descriptors}.
 	 * <p>
 	 * If a header is documented, is not marked as optional, and is not present in the
-	 * response, a failure will occur. If a header is present in the response, but is not
-	 * documented by one of the descriptors, there will be no failure.
+	 * response, a failure will occur.
 	 *
-	 * @param attributes Attributes made available during rendering of the snippet
-	 * @param descriptors The descriptions of the response's headers
-	 * @return the handler
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the response's headers
+	 * @return the snippet that will document the response headers
 	 * @see #headerWithName(String)
 	 */
 	public static Snippet responseHeaders(Map<String, Object> attributes,

spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/RequestHeadersSnippet.java

@@ -56,7 +56,7 @@ public class RequestHeadersSnippet extends AbstractHeadersSnippet {
 	}
 
 	@Override
-	protected Set<String> getHeaders(Operation operation) {
+	protected Set<String> extractActualHeaders(Operation operation) {
 		return operation.getRequest().getHeaders().keySet();
 	}
 

spring-restdocs-core/src/main/java/org/springframework/restdocs/headers/ResponseHeadersSnippet.java

@@ -56,7 +56,7 @@ public class ResponseHeadersSnippet extends AbstractHeadersSnippet {
 	}
 
 	@Override
-	protected Set<String> getHeaders(Operation operation) {
+	protected Set<String> extractActualHeaders(Operation operation) {
 		return operation.getResponse().getHeaders().keySet();
 	}
 

spring-restdocs-core/src/test/java/org/springframework/restdocs/headers/RequestHeadersSnippetTests.java

@@ -44,6 +44,7 @@ import static org.springframework.restdocs.test.SnippetMatchers.tableWithHeader;
  * Tests for {@link RequestHeadersSnippet}.
  *
  * @author Andreas Evers
+ * @author Andy Wilkinson
  */
 public class RequestHeadersSnippetTests {
 
@@ -55,31 +56,36 @@ public class RequestHeadersSnippetTests {
 
 	@Test
 	public void requestWithHeaders() throws IOException {
-		this.snippet.expectRequestHeaders("request-with-headers").withContents(//
-				tableWithHeader("Name", "Description") //
-						.row("X-Test", "one") //
-						.row("Accept", "two") //
-						.row("Accept-Encoding", "three") //
-						.row("Accept-Language", "four") //
-						.row("Cache-Control", "five") //
+		this.snippet.expectRequestHeaders("request-with-headers").withContents(
+				tableWithHeader("Name", "Description").row("X-Test", "one")
+						.row("Accept", "two").row("Accept-Encoding", "three")
+						.row("Accept-Language", "four").row("Cache-Control", "five")
 						.row("Connection", "six"));
 		new RequestHeadersSnippet(Arrays.asList(
-				headerWithName("X-Test").description("one"), //
-				headerWithName("Accept").description("two"), //
-				headerWithName("Accept-Encoding").description("three"), //
-				headerWithName("Accept-Language").description("four"), //
-				headerWithName("Cache-Control").description("five"), //
-				headerWithName("Connection").description("six"))) //
+				headerWithName("X-Test").description("one"), headerWithName("Accept")
+						.description("two"), headerWithName("Accept-Encoding")
+						.description("three"), headerWithName("Accept-Language")
+						.description("four"), headerWithName("Cache-Control")
+						.description("five"),
+				headerWithName("Connection").description("six")))
 				.document(new OperationBuilder("request-with-headers", this.snippet
-						.getOutputDirectory()) //
-						.request("http://localhost") //
-						.header("X-Test", "test") //
-						.header("Accept", "*/*") //
-						.header("Accept-Encoding", "gzip, deflate") //
-						.header("Accept-Language", "en-US,en;q=0.5") //
-						.header("Cache-Control", "max-age=0") //
-						.header("Connection", "keep-alive") //
-						.build());
+						.getOutputDirectory()).request("http://localhost")
+						.header("X-Test", "test").header("Accept", "*/*")
+						.header("Accept-Encoding", "gzip, deflate")
+						.header("Accept-Language", "en-US,en;q=0.5")
+						.header("Cache-Control", "max-age=0")
+						.header("Connection", "keep-alive").build());
+	}
+
+	@Test
+	public void caseInsensitiveRequestHeaders() throws IOException {
+		this.snippet
+				.expectRequestHeaders("case-insensitive-request-headers")
+				.withContents(tableWithHeader("Name", "Description").row("X-Test", "one"));
+		new RequestHeadersSnippet(Arrays.asList(headerWithName("X-Test").description(
+				"one"))).document(new OperationBuilder(
+				"case-insensitive-request-headers", this.snippet.getOutputDirectory())
+				.request("/").header("X-test", "test").build());
 	}
 
 	@Test
@@ -118,9 +124,9 @@ public class RequestHeadersSnippetTests {
 	public void requestHeadersWithCustomDescriptorAttributes() throws IOException {
 		this.snippet.expectRequestHeaders("request-headers-with-custom-attributes")
 				.withContents(//
-						tableWithHeader("Name", "Description", "Foo") //
-								.row("X-Test", "one", "alpha") //
-								.row("Accept-Encoding", "two", "bravo") //
+						tableWithHeader("Name", "Description", "Foo")
+								.row("X-Test", "one", "alpha")
+								.row("Accept-Encoding", "two", "bravo")
 								.row("Accept", "three", "charlie"));
 		TemplateResourceResolver resolver = mock(TemplateResourceResolver.class);
 		given(resolver.resolveTemplateResource("request-headers")).willReturn(

spring-restdocs-core/src/test/java/org/springframework/restdocs/headers/ResponseHeadersSnippetTests.java

@@ -41,9 +41,10 @@ import static org.springframework.restdocs.snippet.Attributes.key;
 import static org.springframework.restdocs.test.SnippetMatchers.tableWithHeader;
 
 /**
- * Tests for {@link ReponseHeadersSnippet}.
+ * Tests for {@link ResponseHeadersSnippet}.
  *
  * @author Andreas Evers
+ * @author Andy Wilkinson
  */
 public class ResponseHeadersSnippetTests {
 
@@ -55,40 +56,41 @@ public class ResponseHeadersSnippetTests {
 
 	@Test
 	public void responseWithHeaders() throws IOException {
-		this.snippet.expectResponseHeaders("response-headers").withContents(//
-				tableWithHeader("Name", "Description") //
-						.row("X-Test", "one") //
-						.row("Content-Type", "two") //
-						.row("Etag", "three") //
-						.row("Content-Length", "four") //
-						.row("Cache-Control", "five") //
-						.row("Vary", "six"));
+		this.snippet.expectResponseHeaders("response-headers").withContents(
+				tableWithHeader("Name", "Description").row("X-Test", "one")
+						.row("Content-Type", "two").row("Etag", "three")
+						.row("Cache-Control", "five").row("Vary", "six"));
 		new ResponseHeadersSnippet(Arrays.asList(
-				headerWithName("X-Test").description("one"), //
-				headerWithName("Content-Type").description("two"), //
-				headerWithName("Etag").description("three"), //
-				headerWithName("Content-Length").description("four"), //
-				headerWithName("Cache-Control").description("five"), //
-				headerWithName("Vary").description("six"))) //
+				headerWithName("X-Test").description("one"),
+				headerWithName("Content-Type").description("two"), headerWithName("Etag")
+						.description("three"), headerWithName("Cache-Control")
+						.description("five"), headerWithName("Vary").description("six")))
 				.document(new OperationBuilder("response-headers", this.snippet
-						.getOutputDirectory()) //
-						.response() //
-						.header("X-Test", "test") //
-						.header("Content-Type", "application/json") //
-						.header("Etag", "lskjadldj3ii32l2ij23") //
-						.header("Content-Length", "19166") //
-						.header("Cache-Control", "max-age=0") //
-						.header("Vary", "User-Agent") //
-						.build());
+						.getOutputDirectory()).response().header("X-Test", "test")
+						.header("Content-Type", "application/json")
+						.header("Etag", "lskjadldj3ii32l2ij23")
+						.header("Cache-Control", "max-age=0")
+						.header("Vary", "User-Agent").build());
+	}
+
+	@Test
+	public void caseInsensitiveResponseHeaders() throws IOException {
+		this.snippet
+				.expectResponseHeaders("case-insensitive-response-headers")
+				.withContents(tableWithHeader("Name", "Description").row("X-Test", "one"));
+		new ResponseHeadersSnippet(Arrays.asList(headerWithName("X-Test").description(
+				"one"))).document(new OperationBuilder(
+				"case-insensitive-response-headers", this.snippet.getOutputDirectory())
+				.response().header("X-test", "test").build());
 	}
 
 	@Test
 	public void responseHeadersWithCustomDescriptorAttributes() throws IOException {
 		this.snippet.expectResponseHeaders("response-headers-with-custom-attributes")
-				.withContents(//
-						tableWithHeader("Name", "Description", "Foo") //
-								.row("X-Test", "one", "alpha") //
-								.row("Content-Type", "two", "bravo") //
+				.withContents(
+						tableWithHeader("Name", "Description", "Foo")
+								.row("X-Test", "one", "alpha")
+								.row("Content-Type", "two", "bravo")
 								.row("Etag", "three", "charlie"));
 		TemplateResourceResolver resolver = mock(TemplateResourceResolver.class);
 		given(resolver.resolveTemplateResource("response-headers")).willReturn(

spring-restdocs-core/src/test/java/org/springframework/restdocs/test/ExpectedSnippet.java

@@ -34,6 +34,7 @@ import static org.junit.Assert.assertThat;
  * generated the expected snippet.
  *
  * @author Andy Wilkinson
+ * @author Andreas Evers
  */
 public class ExpectedSnippet implements TestRule {