Add support for documenting the parts of a multipart request

Closes gh-161

spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestDocumentation.java

@@ -43,6 +43,17 @@ public abstract class RequestDocumentation {
 		return new ParameterDescriptor(name);
 	}
 
+	/**
+	 * Creates a {@link RequestPartDescriptor} that describes a request part with the
+	 * given {@code name}.
+	 *
+	 * @param name The name of the request part
+	 * @return a {@link RequestPartDescriptor} ready for further configuration
+	 */
+	public static RequestPartDescriptor partWithName(String name) {
+		return new RequestPartDescriptor(name);
+	}
+
 	/**
 	 * Returns a {@code Snippet} that will document the path parameters from the API
 	 * operation's request. The parameters will be documented using the given
@@ -207,4 +218,83 @@ public abstract class RequestDocumentation {
 		return new RequestParametersSnippet(Arrays.asList(descriptors), attributes, true);
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the parts from the API operation's
+	 * request. The parts will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a part is present in the request, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a part
+	 * is documented, is not marked as optional, and is not present in the request, a
+	 * failure will also occur.
+	 * <p>
+	 * If you do not want to document a part, a part descriptor can be marked as
+	 * {@link RequestPartDescriptor#ignored}. This will prevent it from appearing in the
+	 * generated snippet while avoiding the failure described above.
+	 *
+	 * @param descriptors The descriptions of the request's parts
+	 * @return the snippet
+	 * @see OperationRequest#getParts()
+	 */
+	public static RequestPartsSnippet requestParts(RequestPartDescriptor... descriptors) {
+		return new RequestPartsSnippet(Arrays.asList(descriptors));
+	}
+
+	/**
+	 * Returns a {@code Snippet} that will document the parts from the API operation's
+	 * request. The parameters will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a part is documented, is not marked as optional, and is not present in the
+	 * request, a failure will occur. Any undocumented parts will be ignored.
+	 *
+	 * @param descriptors The descriptions of the request's parts
+	 * @return the snippet
+	 * @see OperationRequest#getParts()
+	 */
+	public static RequestPartsSnippet relaxedRequestParts(
+			RequestPartDescriptor... descriptors) {
+		return new RequestPartsSnippet(Arrays.asList(descriptors), true);
+	}
+
+	/**
+	 * Returns a {@code Snippet} that will document the parts from the API operation's
+	 * request. The given {@code attributes} will be available during snippet rendering
+	 * and the parts will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a part is present in the request, but is not documented by one of the
+	 * descriptors, a failure will occur when the snippet is invoked. Similarly, if a part
+	 * is documented, is not marked as optional, and is not present in the request, a
+	 * failure will also occur.
+	 * <p>
+	 * If you do not want to document a part, a part descriptor can be marked as
+	 * {@link RequestPartDescriptor#ignored}. This will prevent it from appearing in the
+	 * generated snippet while avoiding the failure described above.
+	 *
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the request's parts
+	 * @return the snippet
+	 * @see OperationRequest#getParts()
+	 */
+	public static RequestPartsSnippet requestParts(Map<String, Object> attributes,
+			RequestPartDescriptor... descriptors) {
+		return new RequestPartsSnippet(Arrays.asList(descriptors), attributes);
+	}
+
+	/**
+	 * Returns a {@code Snippet} that will document the parts from the API operation's
+	 * request. The given {@code attributes} will be available during snippet rendering
+	 * and the parts will be documented using the given {@code descriptors}.
+	 * <p>
+	 * If a part is documented, is not marked as optional, and is not present in the
+	 * request, a failure will occur. Any undocumented parts will be ignored.
+	 *
+	 * @param attributes the attributes
+	 * @param descriptors the descriptions of the request's parts
+	 * @return the snippet
+	 * @see OperationRequest#getParameters()
+	 */
+	public static RequestPartsSnippet relaxedRequestParts(Map<String, Object> attributes,
+			RequestPartDescriptor... descriptors) {
+		return new RequestPartsSnippet(Arrays.asList(descriptors), attributes, true);
+	}
+
 }

spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestPartDescriptor.java

@@ -0,0 +1,73 @@
+/*
+ * Copyright 2014-2016 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.request;
+
+import org.springframework.restdocs.snippet.IgnorableDescriptor;
+
+/**
+ * A descriptor of a request part.
+ *
+ * @author Andy Wilkinson
+ * @see RequestDocumentation#partWithName
+ */
+public class RequestPartDescriptor extends IgnorableDescriptor<RequestPartDescriptor> {
+
+	private final String name;
+
+	private boolean optional;
+
+	/**
+	 * Creates a new {@code RequestPartDescriptor} describing the request part with the
+	 * given {@code name}.
+	 *
+	 * @param name the name of the request part
+	 */
+	protected RequestPartDescriptor(String name) {
+		this.name = name;
+	}
+
+	/**
+	 * Marks the request part as optional.
+	 *
+	 * @return {@code this}
+	 */
+	public final RequestPartDescriptor optional() {
+		this.optional = true;
+		return this;
+	}
+
+	/**
+	 * Returns the name of the request part being described by this descriptor.
+	 *
+	 * @return the name of the parameter
+	 */
+	public final String getName() {
+		return this.name;
+	}
+
+	/**
+	 * Returns {@code true} if the described request part is optional, otherwise
+	 * {@code false}.
+	 *
+	 * @return {@code true} if the described request part is optional, otherwise
+	 * {@code false}
+	 */
+	public final boolean isOptional() {
+		return this.optional;
+	}
+
+}

spring-restdocs-core/src/main/java/org/springframework/restdocs/request/RequestPartsSnippet.java

@@ -0,0 +1,206 @@
+/*
+ * Copyright 2014-2016 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.request;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+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.operation.OperationRequestPart;
+import org.springframework.restdocs.snippet.Snippet;
+import org.springframework.restdocs.snippet.SnippetException;
+import org.springframework.restdocs.snippet.TemplatedSnippet;
+import org.springframework.util.Assert;
+
+/**
+ * A {@link Snippet} that documents the request parts supported by a RESTful resource.
+ *
+ * @author Andy Wilkinson
+ * @see RequestDocumentation#requestParts(RequestPartDescriptor...)
+ * @see RequestDocumentation#requestParts(Map, RequestPartDescriptor...)
+ * @see RequestDocumentation#relaxedRequestParts(RequestPartDescriptor...)
+ * @see RequestDocumentation#relaxedRequestParts(Map, RequestPartDescriptor...)
+ */
+public class RequestPartsSnippet extends TemplatedSnippet {
+
+	private final Map<String, RequestPartDescriptor> descriptorsByName = new LinkedHashMap<>();
+
+	private final boolean ignoreUndocumentedParts;
+
+	/**
+	 * Creates a new {@code RequestPartsSnippet} that will document the request's parts
+	 * using the given {@code descriptors}. Undocumented parts will trigger a failure.
+	 *
+	 * @param descriptors the parameter descriptors
+	 */
+	protected RequestPartsSnippet(List<RequestPartDescriptor> descriptors) {
+		this(descriptors, null, false);
+	}
+
+	/**
+	 * Creates a new {@code RequestPartsSnippet} that will document the request's parts
+	 * using the given {@code descriptors}. If {@code ignoreUndocumentedParts} is
+	 * {@code true}, undocumented parts will be ignored and will not trigger a failure.
+	 *
+	 * @param descriptors the parameter descriptors
+	 * @param ignoreUndocumentedParts whether undocumented parts should be ignored
+	 */
+	protected RequestPartsSnippet(List<RequestPartDescriptor> descriptors,
+			boolean ignoreUndocumentedParts) {
+		this(descriptors, null, ignoreUndocumentedParts);
+	}
+
+	/**
+	 * Creates a new {@code RequestPartsSnippet} that will document the request's parts
+	 * using the given {@code descriptors}. The given {@code attributes} will be included
+	 * in the model during template rendering. Undocumented parts will trigger a failure.
+	 *
+	 * @param descriptors the parameter descriptors
+	 * @param attributes the additional attributes
+	 */
+	protected RequestPartsSnippet(List<RequestPartDescriptor> descriptors,
+			Map<String, Object> attributes) {
+		this(descriptors, attributes, false);
+	}
+
+	/**
+	 * Creates a new {@code RequestPartsSnippet} that will document the request's parts
+	 * using the given {@code descriptors}. The given {@code attributes} will be included
+	 * in the model during template rendering. If {@code ignoreUndocumentedParts} is
+	 * {@code true}, undocumented parts will be ignored and will not trigger a failure.
+	 *
+	 * @param descriptors the parameter descriptors
+	 * @param attributes the additional attributes
+	 * @param ignoreUndocumentedParts whether undocumented parts should be ignored
+	 */
+	protected RequestPartsSnippet(List<RequestPartDescriptor> descriptors,
+			Map<String, Object> attributes, boolean ignoreUndocumentedParts) {
+		super("request-parts", attributes);
+		for (RequestPartDescriptor descriptor : descriptors) {
+			Assert.notNull(descriptor.getName(),
+					"Request part descriptors must have a name");
+			if (!descriptor.isIgnored()) {
+				Assert.notNull(descriptor.getDescription(),
+						"The descriptor for request part '" + descriptor.getName()
+								+ "' must either have a description or be marked as "
+								+ "ignored");
+			}
+			this.descriptorsByName.put(descriptor.getName(), descriptor);
+		}
+		this.ignoreUndocumentedParts = ignoreUndocumentedParts;
+	}
+
+	/**
+	 * Returns a new {@code RequestPartsSnippet} configured with this snippet's attributes
+	 * and its descriptors combined with the given {@code additionalDescriptors}.
+	 *
+	 * @param additionalDescriptors the additional descriptors
+	 * @return the new snippet
+	 */
+	public RequestPartsSnippet and(RequestPartDescriptor... additionalDescriptors) {
+		List<RequestPartDescriptor> combinedDescriptors = new ArrayList<>();
+		combinedDescriptors.addAll(this.descriptorsByName.values());
+		combinedDescriptors.addAll(Arrays.asList(additionalDescriptors));
+		return new RequestPartsSnippet(combinedDescriptors, this.getAttributes());
+	}
+
+	@Override
+	protected Map<String, Object> createModel(Operation operation) {
+		verifyRequestPartDescriptors(operation);
+		Map<String, Object> model = new HashMap<>();
+		List<Map<String, Object>> requestParts = new ArrayList<>();
+		for (Entry<String, RequestPartDescriptor> entry : this.descriptorsByName
+				.entrySet()) {
+			RequestPartDescriptor descriptor = entry.getValue();
+			if (!descriptor.isIgnored()) {
+				requestParts.add(createModelForDescriptor(descriptor));
+			}
+		}
+		model.put("requestParts", requestParts);
+		return model;
+	}
+
+	private void verifyRequestPartDescriptors(Operation operation) {
+		Set<String> actualRequestParts = extractActualRequestParts(operation);
+		Set<String> expectedRequestParts = new HashSet<>();
+		for (Entry<String, RequestPartDescriptor> entry : this.descriptorsByName
+				.entrySet()) {
+			if (!entry.getValue().isOptional()) {
+				expectedRequestParts.add(entry.getKey());
+			}
+		}
+		Set<String> undocumentedRequestParts;
+		if (this.ignoreUndocumentedParts) {
+			undocumentedRequestParts = Collections.emptySet();
+		}
+		else {
+			undocumentedRequestParts = new HashSet<>(actualRequestParts);
+			undocumentedRequestParts.removeAll(this.descriptorsByName.keySet());
+		}
+
+		Set<String> missingRequestParts = new HashSet<>(expectedRequestParts);
+		missingRequestParts.removeAll(actualRequestParts);
+
+		if (!undocumentedRequestParts.isEmpty() || !missingRequestParts.isEmpty()) {
+			verificationFailed(undocumentedRequestParts, missingRequestParts);
+		}
+	}
+
+	private Set<String> extractActualRequestParts(Operation operation) {
+		Set<String> actualRequestParts = new HashSet<>();
+		for (OperationRequestPart requestPart : operation.getRequest().getParts()) {
+			actualRequestParts.add(requestPart.getName());
+		}
+		return actualRequestParts;
+	}
+
+	private void verificationFailed(Set<String> undocumentedRequestParts,
+			Set<String> missingRequestParts) {
+		String message = "";
+		if (!undocumentedRequestParts.isEmpty()) {
+			message += "Request parts with the following names were not documented: "
+					+ undocumentedRequestParts;
+		}
+		if (!missingRequestParts.isEmpty()) {
+			if (message.length() > 0) {
+				message += ". ";
+			}
+			message += "Request parts with the following names were not found in "
+					+ "the request: " + missingRequestParts;
+		}
+		throw new SnippetException(message);
+	}
+
+	private Map<String, Object> createModelForDescriptor(
+			RequestPartDescriptor 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;
+	}
+
+}

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

@@ -0,0 +1,9 @@
+|===
+|Part|Description
+
+{{#requestParts}}
+|`{{name}}`
+|{{description}}
+
+{{/requestParts}}
+|===

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

@@ -0,0 +1,5 @@
+Part | Description
+---- | -----------
+{{#requestParts}}
+`{{name}}` | {{description}}
+{{/requestParts}}