Add support for documenting body of a request, response or request part

Closes gh-318
Closes gh-319

spring-restdocs-core/src/main/java/org/springframework/restdocs/config/SnippetConfigurer.java

@@ -25,6 +25,7 @@ import org.springframework.restdocs.RestDocumentationContext;
 import org.springframework.restdocs.cli.CliDocumentation;
 import org.springframework.restdocs.generate.RestDocumentationGenerator;
 import org.springframework.restdocs.http.HttpDocumentation;
+import org.springframework.restdocs.payload.PayloadDocumentation;
 import org.springframework.restdocs.snippet.Snippet;
 import org.springframework.restdocs.templates.TemplateFormat;
 import org.springframework.restdocs.templates.TemplateFormats;
@@ -42,7 +43,8 @@ public abstract class SnippetConfigurer<PARENT, TYPE>
 
 	private List<Snippet> defaultSnippets = new ArrayList<>(Arrays.asList(
 			CliDocumentation.curlRequest(), CliDocumentation.httpieRequest(),
-			HttpDocumentation.httpRequest(), HttpDocumentation.httpResponse()));
+			HttpDocumentation.httpRequest(), HttpDocumentation.httpResponse(),
+			PayloadDocumentation.requestBody(), PayloadDocumentation.responseBody()));
 
 	/**
 	 * The default encoding for documentation snippets.

spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/AbstractBodySnippet.java

@@ -0,0 +1,125 @@
+/*
+ * 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.payload;
+
+import java.io.IOException;
+import java.nio.charset.Charset;
+import java.util.HashMap;
+import java.util.Map;
+
+import org.springframework.http.MediaType;
+import org.springframework.restdocs.operation.Operation;
+import org.springframework.restdocs.snippet.ModelCreationException;
+import org.springframework.restdocs.snippet.TemplatedSnippet;
+
+/**
+ * Abstract {@link TemplatedSnippet} subclass that provides a base for snippets that
+ * document a RESTful resource's request or response body.
+ *
+ * @author Andy Wilkinson
+ */
+public abstract class AbstractBodySnippet extends TemplatedSnippet {
+
+	private final PayloadSubsectionExtractor<?> subsectionExtractor;
+
+	/**
+	 * Creates a new {@code AbstractBodySnippet} that will produce a snippet named
+	 * {@code <type>-body} using a template named {@code <type>-body}. The snippet will
+	 * contain the subsection of the body extracted by the given
+	 * {@code subsectionExtractor}. The given {@code attributes} will be included in the
+	 * model during template rendering
+	 *
+	 * @param type the type of the body
+	 * @param subsectionExtractor the subsection extractor
+	 * @param attributes the attributes
+	 */
+	protected AbstractBodySnippet(String type,
+			PayloadSubsectionExtractor<?> subsectionExtractor,
+			Map<String, Object> attributes) {
+		this(type, type, subsectionExtractor, attributes);
+	}
+
+	/**
+	 * Creates a new {@code AbstractBodySnippet} that will produce a snippet named
+	 * {@code <name>-body} using a template named {@code <type>-body}. The snippet will
+	 * contain the subsection of the body extracted by the given
+	 * {@code subsectionExtractor}. The given {@code attributes} will be included in the
+	 * model during template rendering
+	 *
+	 * @param name the name of the snippet
+	 * @param type the type of the body
+	 * @param subsectionExtractor the subsection extractor
+	 * @param attributes the attributes
+	 */
+	protected AbstractBodySnippet(String name, String type,
+			PayloadSubsectionExtractor<?> subsectionExtractor,
+			Map<String, Object> attributes) {
+		super(name + "-body"
+				+ (subsectionExtractor != null
+						? "-" + subsectionExtractor.getSubsectionId() : ""),
+				type + "-body", attributes);
+		this.subsectionExtractor = subsectionExtractor;
+	}
+
+	@Override
+	protected Map<String, Object> createModel(Operation operation) {
+		try {
+			MediaType contentType = getContentType(operation);
+			byte[] content = getContent(operation);
+			if (this.subsectionExtractor != null) {
+				content = this.subsectionExtractor.extractSubsection(content,
+						contentType);
+			}
+			Charset charset = extractCharset(contentType);
+			String body = charset != null ? new String(content, charset)
+					: new String(content);
+			Map<String, Object> model = new HashMap<>();
+			model.put("body", body);
+			return model;
+		}
+		catch (IOException ex) {
+			throw new ModelCreationException(ex);
+		}
+	}
+
+	private Charset extractCharset(MediaType contentType) {
+		if (contentType == null) {
+			return null;
+		}
+		return contentType.getCharset();
+	}
+
+	/**
+	 * Returns the content of the request or response extracted from the given
+	 * {@code operation}.
+	 *
+	 * @param operation The operation
+	 * @return The content
+	 * @throws IOException if the content cannot be extracted
+	 */
+	protected abstract byte[] getContent(Operation operation) throws IOException;
+
+	/**
+	 * Returns the content type of the request or response extracted from the given
+	 * {@code operation}.
+	 *
+	 * @param operation The operation
+	 * @return The content type
+	 */
+	protected abstract MediaType getContentType(Operation operation);
+
+}

spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/PayloadDocumentation.java

@@ -1443,6 +1443,164 @@ public abstract class PayloadDocumentation {
 				true);
 	}
 
+	/**
+	 * Returns a {@code Snippet} that will document the body of the API operation's
+	 * request payload.
+	 *
+	 * @return the snippet that will document the request body
+	 */
+	public static RequestBodySnippet requestBody() {
+		return new RequestBodySnippet();
+	}
+
+	/**
+	 * Returns a {@code Snippet} that will document the body of the API operation's
+	 * request payload. The given attributes will be made available during snippet
+	 * generation.
+	 *
+	 * @param attributes the attributes
+	 * @return the snippet that will document the request body
+	 */
+	public static RequestBodySnippet requestBody(Map<String, Object> attributes) {
+		return new RequestBodySnippet(attributes);
+	}
+
+	/**
+	 * Returns a {@code Snippet} that will document a subsection of the body of the API
+	 * operation's request payload. The subsection will be extracted using the given
+	 * {@code subsectionExtractor}.
+	 *
+	 * @param subsectionExtractor the subsection extractor
+	 * @return the snippet that will document the request body subsection
+	 */
+	public static RequestBodySnippet requestBody(
+			PayloadSubsectionExtractor<?> subsectionExtractor) {
+		return new RequestBodySnippet(subsectionExtractor);
+	}
+
+	/**
+	 * Returns a {@code Snippet} that will document a subsection of the body of the API
+	 * operation's request payload. The subsection will be extracted using the given
+	 * {@code subsectionExtractor}. The given attributes will be made available during
+	 * snippet generation.
+	 *
+	 * @param subsectionExtractor the subsection extractor
+	 * @param attributes the attributes
+	 * @return the snippet that will document the request body subsection
+	 */
+	public static RequestBodySnippet requestBody(
+			PayloadSubsectionExtractor<?> subsectionExtractor,
+			Map<String, Object> attributes) {
+		return new RequestBodySnippet(subsectionExtractor, attributes);
+	}
+
+	/**
+	 * Returns a {@code Snippet} that will document the body of the API operation's
+	 * response payload.
+	 *
+	 * @return the snippet that will document the response body
+	 */
+	public static ResponseBodySnippet responseBody() {
+		return new ResponseBodySnippet();
+	}
+
+	/**
+	 * Returns a {@code Snippet} that will document the body of the API operation's
+	 * response payload. The given attributes will be made available during snippet
+	 * generation.
+	 *
+	 * @param attributes the attributes
+	 * @return the snippet that will document the response body
+	 */
+	public static ResponseBodySnippet responseBody(Map<String, Object> attributes) {
+		return new ResponseBodySnippet(attributes);
+	}
+
+	/**
+	 * Returns a {@code Snippet} that will document a subsection of the body of the API
+	 * operation's response payload. The subsection will be extracted using the given
+	 * {@code subsectionExtractor}.
+	 *
+	 * @param subsectionExtractor the subsection extractor
+	 * @return the snippet that will document the response body subsection
+	 */
+	public static ResponseBodySnippet responseBody(
+			PayloadSubsectionExtractor<?> subsectionExtractor) {
+		return new ResponseBodySnippet(subsectionExtractor);
+	}
+
+	/**
+	 * Returns a {@code Snippet} that will document a subsection of the body of the API
+	 * operation's response payload. The subsection will be extracted using the given
+	 * {@code subsectionExtractor}. The given attributes will be made available during
+	 * snippet generation.
+	 *
+	 * @param subsectionExtractor the subsection extractor
+	 * @param attributes the attributes
+	 * @return the snippet that will document the response body subsection
+	 */
+	public static ResponseBodySnippet responseBody(
+			PayloadSubsectionExtractor<?> subsectionExtractor,
+			Map<String, Object> attributes) {
+		return new ResponseBodySnippet(subsectionExtractor, attributes);
+	}
+
+	/**
+	 * Returns a {@code Snippet} that will document the body of specified part of the API
+	 * operation's request payload.
+	 *
+	 * @param partName the name of the request part
+	 * @return the snippet that will document the response body
+	 */
+	public static RequestPartBodySnippet requestPartBody(String partName) {
+		return new RequestPartBodySnippet(partName);
+	}
+
+	/**
+	 * Returns a {@code Snippet} that will document the body of specified part of the API
+	 * operation's request payload. The given attributes will be made available during
+	 * snippet generation.
+	 *
+	 * @param partName the name of the request part
+	 * @param attributes the attributes
+	 * @return the snippet that will document the response body
+	 */
+	public static RequestPartBodySnippet requestPartBody(String partName,
+			Map<String, Object> attributes) {
+		return new RequestPartBodySnippet(partName, attributes);
+	}
+
+	/**
+	 * Returns a {@code Snippet} that will document a subsection of the body of specified
+	 * part of the API operation's request payload. The subsection will be extracted using
+	 * the given {@code subsectionExtractor}.
+	 *
+	 * @param partName the name of the request part
+	 * @param subsectionExtractor the subsection extractor
+	 * @return the snippet that will document the response body
+	 */
+	public static RequestPartBodySnippet requestPartBody(String partName,
+			PayloadSubsectionExtractor<?> subsectionExtractor) {
+		return new RequestPartBodySnippet(partName, subsectionExtractor);
+	}
+
+	/**
+	 * Returns a {@code Snippet} that will document a subsection of the body of specified
+	 * part of the API operation's request payload. The subsection will be extracted using
+	 * the given {@code subsectionExtractor}. The given attributes will be made available
+	 * during snippet generation.
+	 *
+	 * @param partName the name of the request part
+	 * @param subsectionExtractor the subsection extractor
+	 * @param attributes the attributes
+	 * @return the snippet that will document the response body
+	 */
+	public static RequestPartBodySnippet requestPartBody(String partName,
+			PayloadSubsectionExtractor<?> subsectionExtractor,
+			Map<String, Object> attributes) {
+		return new RequestPartBodySnippet(partName, subsectionExtractor, attributes);
+	}
+
 	/**
 	 * Creates a copy of the given {@code descriptors} with the given {@code pathPrefix}
 	 * applied to their paths.

spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/RequestBodySnippet.java

@@ -0,0 +1,84 @@
+/*
+ * 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.payload;
+
+import java.io.IOException;
+import java.util.Map;
+
+import org.springframework.http.MediaType;
+import org.springframework.restdocs.operation.Operation;
+import org.springframework.restdocs.snippet.Snippet;
+
+/**
+ * A {@link Snippet} that documents the body of a request.
+ *
+ * @author Andy Wilkinson
+ */
+public class RequestBodySnippet extends AbstractBodySnippet {
+
+	/**
+	 * Creates a new {@code RequestBodySnippet}.
+	 */
+	public RequestBodySnippet() {
+		this(null, null);
+	}
+
+	/**
+	 * Creates a new {@code RequestBodySnippet} that will document the subsection of the
+	 * request body extracted by the given {@code subsectionExtractor}.
+	 *
+	 * @param subsectionExtractor the subsection extractor
+	 */
+	public RequestBodySnippet(PayloadSubsectionExtractor<?> subsectionExtractor) {
+		this(subsectionExtractor, null);
+	}
+
+	/**
+	 * Creates a new {@code RequestBodySnippet} with the given additional
+	 * {@code attributes} that will be included in the model during template rendering.
+	 *
+	 * @param attributes The additional attributes
+	 */
+	public RequestBodySnippet(Map<String, Object> attributes) {
+		this(null, attributes);
+	}
+
+	/**
+	 * Creates a new {@code RequestBodySnippet} that will document the subsection of the
+	 * request body extracted by the given {@code subsectionExtractor}. The given
+	 * additional {@code attributes} that will be included in the model during template
+	 * rendering.
+	 *
+	 * @param subsectionExtractor the subsection extractor
+	 * @param attributes The additional attributes
+	 */
+	public RequestBodySnippet(PayloadSubsectionExtractor<?> subsectionExtractor,
+			Map<String, Object> attributes) {
+		super("request", subsectionExtractor, attributes);
+	}
+
+	@Override
+	protected byte[] getContent(Operation operation) throws IOException {
+		return operation.getRequest().getContent();
+	}
+
+	@Override
+	protected MediaType getContentType(Operation operation) {
+		return operation.getRequest().getHeaders().getContentType();
+	}
+
+}

spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/RequestPartBodySnippet.java

@@ -0,0 +1,111 @@
+/*
+ * 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.payload;
+
+import java.io.IOException;
+import java.util.Map;
+
+import org.springframework.http.MediaType;
+import org.springframework.restdocs.operation.Operation;
+import org.springframework.restdocs.operation.OperationRequestPart;
+import org.springframework.restdocs.snippet.Snippet;
+import org.springframework.restdocs.snippet.SnippetException;
+
+/**
+ * A {@link Snippet} that documents the body of a request part.
+ *
+ * @author Andy Wilkinson
+ */
+public class RequestPartBodySnippet extends AbstractBodySnippet {
+
+	private final String partName;
+
+	/**
+	 * Creates a new {@code RequestPartBodySnippet} that will document the body of the
+	 * request part with the given {@code partName}.
+	 *
+	 * @param partName the name of the request part
+	 */
+	public RequestPartBodySnippet(String partName) {
+		this(partName, null, null);
+	}
+
+	/**
+	 * Creates a new {@code RequestPartBodySnippet} that will document the subsection of
+	 * the body of the request part with the given {@code partName} extracted by the given
+	 * {@code subsectionExtractor}.
+	 *
+	 * @param partName the name of the request part
+	 * @param subsectionExtractor the subsection extractor
+	 */
+	public RequestPartBodySnippet(String partName,
+			PayloadSubsectionExtractor<?> subsectionExtractor) {
+		this(partName, subsectionExtractor, null);
+	}
+
+	/**
+	 * Creates a new {@code RequestPartBodySnippet} that will document the body of the
+	 * request part with the given {@code partName}. The given additional
+	 * {@code attributes} will be included in the model during template rendering.
+	 *
+	 * @param partName the name of the request part
+	 * @param attributes the additional attributes
+	 */
+	public RequestPartBodySnippet(String partName, Map<String, Object> attributes) {
+		this(partName, null, attributes);
+	}
+
+	/**
+	 * Creates a new {@code RequestPartBodySnippet} that will document the body of the
+	 * request part with the given {@code partName}. The subsection of the body extracted
+	 * by the given {@code subsectionExtractor} will be documented and the given
+	 * additional {@code attributes} that will be included in the model during template
+	 * rendering.
+	 *
+	 * @param partName the name of the request part
+	 * @param subsectionExtractor the subsection extractor
+	 * @param attributes The additional attributes
+	 */
+	public RequestPartBodySnippet(String partName,
+			PayloadSubsectionExtractor<?> subsectionExtractor,
+			Map<String, Object> attributes) {
+		super("request-part-" + partName, "request-part", subsectionExtractor,
+				attributes);
+		this.partName = partName;
+	}
+
+	@Override
+	protected byte[] getContent(Operation operation) throws IOException {
+		return findPart(operation).getContent();
+	}
+
+	@Override
+	protected MediaType getContentType(Operation operation) {
+		return findPart(operation).getHeaders().getContentType();
+	}
+
+	private OperationRequestPart findPart(Operation operation) {
+		for (OperationRequestPart candidate : operation.getRequest().getParts()) {
+			if (candidate.getName().equals(this.partName)) {
+				return candidate;
+			}
+		}
+		throw new SnippetException("A request part named '" + this.partName
+				+ "' was not found in the request");
+	}
+
+}

spring-restdocs-core/src/main/java/org/springframework/restdocs/payload/ResponseBodySnippet.java

@@ -0,0 +1,84 @@
+/*
+ * 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.payload;
+
+import java.io.IOException;
+import java.util.Map;
+
+import org.springframework.http.MediaType;
+import org.springframework.restdocs.operation.Operation;
+import org.springframework.restdocs.snippet.Snippet;
+
+/**
+ * A {@link Snippet} that documents the body of a response.
+ *
+ * @author Andy Wilkinson
+ */
+public class ResponseBodySnippet extends AbstractBodySnippet {
+
+	/**
+	 * Creates a new {@code ResponseBodySnippet}.
+	 */
+	public ResponseBodySnippet() {
+		this(null, null);
+	}
+
+	/**
+	 * Creates a new {@code ResponseBodySnippet} that will document the subsection of the
+	 * response body extracted by the given {@code subsectionExtractor}.
+	 *
+	 * @param subsectionExtractor the subsection extractor
+	 */
+	public ResponseBodySnippet(PayloadSubsectionExtractor<?> subsectionExtractor) {
+		this(subsectionExtractor, null);
+	}
+
+	/**
+	 * Creates a new {@code ResponseBodySnippet} with the given additional
+	 * {@code attributes} that will be included in the model during template rendering.
+	 *
+	 * @param attributes The additional attributes
+	 */
+	public ResponseBodySnippet(Map<String, Object> attributes) {
+		this(null, attributes);
+	}
+
+	/**
+	 * Creates a new {@code ResponseBodySnippet} that will document the subsection of the
+	 * response body extracted by the given {@code subsectionExtractor}. The given
+	 * additional {@code attributes} that will be included in the model during template
+	 * rendering.
+	 *
+	 * @param subsectionExtractor the subsection extractor
+	 * @param attributes The additional attributes
+	 */
+	public ResponseBodySnippet(PayloadSubsectionExtractor<?> subsectionExtractor,
+			Map<String, Object> attributes) {
+		super("response", subsectionExtractor, attributes);
+	}
+
+	@Override
+	protected byte[] getContent(Operation operation) throws IOException {
+		return operation.getResponse().getContent();
+	}
+
+	@Override
+	protected MediaType getContentType(Operation operation) {
+		return operation.getResponse().getHeaders().getContentType();
+	}
+
+}

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

@@ -0,0 +1,4 @@
+[source,options="nowrap"]
+----
+{{body}}
+----

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

@@ -0,0 +1,4 @@
+[source,options="nowrap"]
+----
+{{body}}
+----

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

@@ -0,0 +1,4 @@
+[source,options="nowrap"]
+----
+{{body}}
+----

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

@@ -0,0 +1,3 @@
+```
+{{body}}
+```

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

@@ -0,0 +1,3 @@
+```
+{{body}}
+```

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

@@ -0,0 +1,3 @@
+```
+{{body}}
+```