Add support for documenting the parts of a multipart request

Closes gh-161

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

@@ -527,6 +527,55 @@ above.
 
 
 
+[[documenting-your-api-request-parts]]
+=== Request parts
+
+The parts of a multipart request can be documenting using `requestParts`. For example:
+
+[source,java,indent=0,role="primary"]
+.MockMvc
+----
+include::{examples-dir}/com/example/mockmvc/RequestParts.java[tags=request-parts]
+----
+<1> Perform a `POST` request with a single part named `file`.
+<2> Configure Spring REST Docs to produce a snippet describing the request's parts. Uses
+	the static `requestParts` method on
+	`org.springframework.restdocs.request.RequestDocumentation`.
+<3> Document the part named `file`. Uses the static `partWithName` method on
+	`org.springframework.restdocs.request.RequestDocumentation`.
+
+[source,java,indent=0,role="secondary"]
+.REST Assured
+----
+include::{examples-dir}/com/example/restassured/RequestParts.java[tags=request-parts]
+----
+<1> Configure Spring REST Docs to produce a snippet describing the request's parts. Uses
+	the static `requestParts` method on
+	`org.springframework.restdocs.request.RequestDocumentation`.
+<2> Document the part named `file`. Uses the static `partWithName` method on
+	`org.springframework.restdocs.request.RequestDocumentation`.
+<3> Configure the request with the part named `file`.
+<4> Perform the `POST` request to `/upload`.
+
+The result is a snippet named `request-parts.adoc` that contains a table describing the
+request parts that are supported by the resource.
+
+When documenting request parts, the test will fail if an undocumented part is used in the
+request. Similarly, the test will also fail if a documented part is not found in the
+request and the part has not been marked as optional.
+
+Request parts can also be documented in a relaxed mode where any undocumented
+parts will not cause a test failure. To do so, use the `relaxedRequestParts` method on
+`org.springframework.restdocs.request.RequestDocumentation`. This can be useful
+when documenting a particular scenario where you only want to focus on a subset of the
+request parts.
+
+If you do not want to document a request part, you can mark it as ignored. This will
+prevent it from appearing in the generated snippet while avoiding the failure described
+above.
+
+
+
 [[documenting-your-api-http-headers]]
 === HTTP headers
 

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

@@ -0,0 +1,41 @@
+/*
+ * 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 com.example.mockmvc;
+
+import org.springframework.test.web.servlet.MockMvc;
+
+import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
+import static org.springframework.restdocs.request.RequestDocumentation.partWithName;
+import static org.springframework.restdocs.request.RequestDocumentation.requestParts;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.fileUpload;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+public class RequestParts {
+
+	private MockMvc mockMvc;
+
+	public void upload() throws Exception {
+		// tag::request-parts[]
+		this.mockMvc.perform(fileUpload("/upload").file("file", "example".getBytes())) // <1>
+			.andExpect(status().isOk())
+			.andDo(document("upload", requestParts( // <2>
+					partWithName("file").description("The file to upload")) // <3>
+		));
+		// end::request-parts[]
+	}
+
+}

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

@@ -0,0 +1,42 @@
+/*
+ * 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 com.example.restassured;
+
+import com.jayway.restassured.RestAssured;
+import com.jayway.restassured.specification.RequestSpecification;
+
+import static org.hamcrest.CoreMatchers.is;
+import static org.springframework.restdocs.request.RequestDocumentation.partWithName;
+import static org.springframework.restdocs.request.RequestDocumentation.requestParts;
+import static org.springframework.restdocs.restassured.RestAssuredRestDocumentation.document;
+
+public class RequestParts {
+
+	private RequestSpecification spec;
+
+	public void upload() throws Exception {
+		// tag::request-parts[]
+		RestAssured.given(this.spec)
+			.filter(document("users", requestParts( // <1>
+					partWithName("file").description("The file to upload")))) // <2>
+			.multiPart("file", "example") // <3>
+			.when().post("/upload") // <4>
+			.then().statusCode(is(200));
+		// end::request-parts[]
+	}
+
+}