Add support for documenting HTTP headers

This commit adds support for documenting HTTP headers in both requests
and responses.

Closes gh-140

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

@@ -0,0 +1,147 @@
+/*
+ * Copyright 2014-2015 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
+ *
+ *      http://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.headers;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+import org.springframework.restdocs.operation.Operation;
+import org.springframework.restdocs.snippet.SnippetException;
+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 headers.
+ *
+ * @author Andreas Evers
+ */
+public abstract class AbstractHeadersSnippet extends TemplatedSnippet {
+
+	private List<HeaderDescriptor> headerDescriptors;
+
+	private String type;
+
+	/**
+	 * Creates a new {@code AbstractHeadersSnippet} that will produce a snippet named
+	 * {@code <type>-headers}. The headers 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 headers
+	 * @param descriptors the header descriptors
+	 * @param attributes the additional attributes
+	 */
+	protected AbstractHeadersSnippet(String type, List<HeaderDescriptor> descriptors,
+			Map<String, Object> attributes) {
+		super(type + "-headers", attributes);
+		for (HeaderDescriptor descriptor : descriptors) {
+			Assert.notNull(descriptor.getName());
+			Assert.notNull(descriptor.getDescription());
+		}
+		this.headerDescriptors = descriptors;
+		this.type = type;
+	}
+
+	@Override
+	protected Map<String, Object> createModel(Operation operation) {
+		validateHeaderDocumentation(operation);
+
+		Map<String, Object> model = new HashMap<>();
+		List<Map<String, Object>> headers = new ArrayList<>();
+		model.put("headers", headers);
+		for (HeaderDescriptor descriptor : this.headerDescriptors) {
+			headers.add(createModelForDescriptor(descriptor));
+		}
+		return model;
+	}
+
+	private void validateHeaderDocumentation(Operation operation) {
+		List<HeaderDescriptor> missingHeaders = findMissingHeaders(operation);
+
+		if (!missingHeaders.isEmpty()) {
+			String message = "";
+			if (!missingHeaders.isEmpty()) {
+				List<String> names = new ArrayList<String>();
+				for (HeaderDescriptor headerDescriptor : missingHeaders) {
+					names.add(headerDescriptor.getName());
+				}
+				message += "Headers with the following names were not found in the "
+						+ this.type + ": " + names;
+			}
+			throw new SnippetException(message);
+		}
+	}
+
+	/**
+	 * 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
+	 * @return descriptors for the headers that are missing from the operation
+	 */
+	protected List<HeaderDescriptor> findMissingHeaders(Operation operation) {
+		List<HeaderDescriptor> missingHeaders = new ArrayList<HeaderDescriptor>();
+		for (HeaderDescriptor headerDescriptor : this.headerDescriptors) {
+			if (!headerDescriptor.isOptional()
+					&& !getHeaders(operation).contains(headerDescriptor.getName())) {
+				missingHeaders.add(headerDescriptor);
+			}
+		}
+
+		return missingHeaders;
+	}
+
+	/**
+	 * Returns the headers of the request or response extracted form the given
+	 * {@code operation}.
+	 *
+	 * @param operation The operation
+	 * @return The headers
+	 */
+	protected abstract Set<String> getHeaders(Operation operation);
+
+	/**
+	 * Returns the list of {@link HeaderDescriptor HeaderDescriptors} that will be used to
+	 * generate the documentation.
+	 *
+	 * @return the header descriptors
+	 */
+	protected final List<HeaderDescriptor> getHeaderDescriptors() {
+		return this.headerDescriptors;
+	}
+
+	/**
+	 * Returns a model for the given {@code descriptor}.
+	 *
+	 * @param descriptor the descriptor
+	 * @return the model
+	 */
+	protected Map<String, Object> createModelForDescriptor(HeaderDescriptor descriptor) {
+		Map<String, Object> model = new HashMap<String, Object>();
+		model.put("name", descriptor.getName());
+		model.put("description", descriptor.getDescription());
+		model.put("optional", descriptor.isOptional());
+		model.putAll(descriptor.getAttributes());
+		return model;
+	}
+
+}

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

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2014-2015 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
+ *
+ *      http://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.headers;
+
+import org.springframework.http.HttpHeaders;
+import org.springframework.restdocs.snippet.AbstractDescriptor;
+
+/**
+ * A description of a header found in a request or response.
+ *
+ * @author Andreas Evers
+ * @see HeaderDocumentation#headerWithName(String)
+ */
+public class HeaderDescriptor extends AbstractDescriptor<HeaderDescriptor> {
+
+	private final String name;
+
+	private boolean optional;
+
+	/**
+	 * Creates a new {@code HeaderDescriptor} describing the header with the given
+	 * {@code name}.
+	 * @param name the name
+	 * @see HttpHeaders
+	 */
+	protected HeaderDescriptor(String name) {
+		this.name = name;
+	}
+
+	/**
+	 * Marks the header as optional.
+	 *
+	 * @return {@code this}
+	 */
+	public final HeaderDescriptor optional() {
+		this.optional = true;
+		return this;
+	}
+
+	/**
+	 * Returns the name for the header.
+	 *
+	 * @return the header name
+	 */
+	public String getName() {
+		return this.name;
+	}
+
+	/**
+	 * Returns {@code true} if the described header is optional, otherwise {@code false}.
+	 *
+	 * @return {@code true} if the described header is optional, otherwise {@code false}
+	 */
+	public final boolean isOptional() {
+		return this.optional;
+	}
+
+}

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

@@ -0,0 +1,116 @@
+/*
+ * Copyright 2014-2015 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
+ *
+ *      http://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.headers;
+
+import java.util.Arrays;
+import java.util.Map;
+
+import org.springframework.restdocs.snippet.Snippet;
+
+/**
+ * Static factory methods for documenting a RESTful API's request and response headers.
+ *
+ * @author Andreas Evers
+ */
+public abstract class HeaderDocumentation {
+
+	private HeaderDocumentation() {
+
+	}
+
+	/**
+	 * Creates a {@code HeaderDescriptor} that describes a header with the given
+	 * {@code name}.
+	 *
+	 * @param name The name of the header
+	 * @return a {@code HeaderDescriptor} ready for further configuration
+	 */
+	public static HeaderDescriptor headerWithName(String name) {
+		return new HeaderDescriptor(name);
+	}
+
+	/**
+	 * Returns a handler that will produce a snippet documenting the headers of the API
+	 * call's request.
+	 * <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.
+	 *
+	 * @param descriptors The descriptions of the request's headers
+	 * @return the handler
+	 * @see #headerWithName(String)
+	 */
+	public static Snippet requestHeaders(HeaderDescriptor... descriptors) {
+		return new RequestHeadersSnippet(Arrays.asList(descriptors));
+	}
+
+	/**
+	 * 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.
+	 * <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.
+	 *
+	 * @param attributes Attributes made available during rendering of the snippet
+	 * @param descriptors The descriptions of the request's headers
+	 * @return the handler
+	 * @see #headerWithName(String)
+	 */
+	public static Snippet requestHeaders(Map<String, Object> attributes,
+			HeaderDescriptor... descriptors) {
+		return new RequestHeadersSnippet(Arrays.asList(descriptors), attributes);
+	}
+
+	/**
+	 * Returns a handler that will produce a snippet documenting the headers of the API
+	 * call's response.
+	 * <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.
+	 *
+	 * @param descriptors The descriptions of the response's headers
+	 * @return the handler
+	 * @see #headerWithName(String)
+	 */
+	public static Snippet responseHeaders(HeaderDescriptor... descriptors) {
+		return new ResponseHeadersSnippet(Arrays.asList(descriptors));
+	}
+
+	/**
+	 * 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.
+	 * <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.
+	 *
+	 * @param attributes Attributes made available during rendering of the snippet
+	 * @param descriptors The descriptions of the response's headers
+	 * @return the handler
+	 * @see #headerWithName(String)
+	 */
+	public static Snippet responseHeaders(Map<String, Object> attributes,
+			HeaderDescriptor... descriptors) {
+		return new ResponseHeadersSnippet(Arrays.asList(descriptors), attributes);
+	}
+
+}

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

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2014-2015 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
+ *
+ *      http://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.headers;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+import org.springframework.restdocs.operation.Operation;
+import org.springframework.restdocs.snippet.Snippet;
+
+/**
+ * A {@link Snippet} that documents the headers in a request.
+ *
+ * @author Andreas Evers
+ * @see HeaderDocumentation#requestHeaders(HeaderDescriptor...)
+ * @see HeaderDocumentation#requestHeaders(Map, HeaderDescriptor...)
+ */
+public class RequestHeadersSnippet extends AbstractHeadersSnippet {
+
+	/**
+	 * Creates a new {@code RequestHeadersSnippet} that will document the headers in the
+	 * request using the given {@code descriptors}.
+	 *
+	 * @param descriptors the descriptors
+	 */
+	protected RequestHeadersSnippet(List<HeaderDescriptor> descriptors) {
+		this(descriptors, null);
+	}
+
+	/**
+	 * Creates a new {@code RequestHeadersSnippet} that will document the headers in the
+	 * request using the given {@code descriptors}. The given {@code attributes} will be
+	 * included in the model during template rendering.
+	 *
+	 * @param descriptors the descriptors
+	 * @param attributes the additional attributes
+	 */
+	protected RequestHeadersSnippet(List<HeaderDescriptor> descriptors,
+			Map<String, Object> attributes) {
+		super("request", descriptors, attributes);
+	}
+
+	@Override
+	protected Set<String> getHeaders(Operation operation) {
+		return operation.getRequest().getHeaders().keySet();
+	}
+
+}

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

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2014-2015 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
+ *
+ *      http://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.headers;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+import org.springframework.restdocs.operation.Operation;
+import org.springframework.restdocs.snippet.Snippet;
+
+/**
+ * A {@link Snippet} that documents the headers in a response.
+ *
+ * @author Andreas Evers
+ * @see HeaderDocumentation#responseHeaders(HeaderDescriptor...)
+ * @see HeaderDocumentation#responseHeaders(Map, HeaderDescriptor...)
+ */
+public class ResponseHeadersSnippet extends AbstractHeadersSnippet {
+
+	/**
+	 * Creates a new {@code ResponseHeadersSnippet} that will document the headers in the
+	 * response using the given {@code descriptors}.
+	 *
+	 * @param descriptors the descriptors
+	 */
+	protected ResponseHeadersSnippet(List<HeaderDescriptor> descriptors) {
+		this(descriptors, null);
+	}
+
+	/**
+	 * Creates a new {@code ResponseHeadersSnippet} that will document the headers in the
+	 * response using the given {@code descriptors}. The given {@code attributes} will be
+	 * included in the model during template rendering.
+	 *
+	 * @param descriptors the descriptors
+	 * @param attributes the additional attributes
+	 */
+	protected ResponseHeadersSnippet(List<HeaderDescriptor> descriptors,
+			Map<String, Object> attributes) {
+		super("response", descriptors, attributes);
+	}
+
+	@Override
+	protected Set<String> getHeaders(Operation operation) {
+		return operation.getResponse().getHeaders().keySet();
+	}
+
+}

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

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2014-2015 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
+ *
+ *      http://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.
+ */
+
+/**
+ * Documenting the headers of a RESTful API's requests and responses.
+ */
+package org.springframework.restdocs.headers;

spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/default-request-headers.snippet

@@ -0,0 +1,9 @@
+|===
+|Name|Description
+
+{{#headers}}
+|{{name}}
+|{{description}}
+
+{{/headers}}
+|===

spring-restdocs-core/src/main/resources/org/springframework/restdocs/templates/default-response-headers.snippet

@@ -0,0 +1,9 @@
+|===
+|Name|Description
+
+{{#headers}}
+|{{name}}
+|{{description}}
+
+{{/headers}}
+|===