Provide support for documenting path parameters

This commit adds support for documenting a request's path parameters.
For example:

mockMvc.perform(
		get("/locations/{latitude}/{longitude}", 51.5072, 0.1275))
			.andExpect(status().isOk())
			.andDo(document("locations").withPathParameters(
					parameterWithName("latitude")
							.description("The location's latitude"),
					parameterWithName("longitude")
							.description("The location's longitude")
			));

Closes gh-86

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

@@ -196,6 +196,32 @@ is not found in the request.
 
 
 
+[[documenting-your-api-path-parameters]]
+=== Path parameters
+
+A request's path parameters can be documented using `withPathParameters`
+
+[source,java,indent=0]
+----
+include::{examples-dir}/com/example/PathParameters.java[tags=path-parameters]
+----
+<1> Build the request. Uses the static `get` method on `RestDocumentationRequestBuilders`.
+<2> Use `withPathParameters` to describe the path parameters.
+<3> Document a parameter named `longitude`. Uses the static `parameterWithName` method on
+`org.springframework.restdocs.request.RequestDocumentation`.
+<4> Document a parameter named `latitude`.
+
+The result is a snippet named `path-parameters.adoc` that contains a table describing
+the path parameters that are supported by the resource.
+
+When documenting path parameters, the test will fail if an undocumented path parameter
+is used in the request. Similarly, the test will also fail if a documented path parameter
+is not found in the request.
+
+TIP: To make the path parameters available for documentation, the request must be
+built using one of the methods on `RestDocumentationRequestBuilders` rather than
+`MockMvcRequestBuilders`.
+
 [[documenting-your-api-default-snippets]]
 === Default snippets
 
@@ -286,8 +312,8 @@ override the template for the `curl-request.adoc` snippet, create a template nam
 
 There are two ways to provide extra information for inclusion in a generated snippet:
 
-. Use the `attributes` method on a field, link or query parameter descriptor to add one or
-  more attributes to an individual descriptor
+. Use the `attributes` method on a field, link or parameter descriptor to add one or more
+  attributes to an individual descriptor.
 . Pass in some attributes when calling `withCurlRequest`, `withHttpRequest`,
   `withHttpResponse`, etc on `RestDocumentationResultHandler`. Such attributes will be
   associated with the snippet as a whole.

docs/src/test/java/com/example/Hypermedia.java

@@ -17,7 +17,7 @@
 package com.example;
 
 import static org.springframework.restdocs.RestDocumentation.document;
-import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.restdocs.RestDocumentationRequestBuilders.get;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.linkWithRel;
 import static org.springframework.restdocs.hypermedia.LinkExtractors.halLinks;

docs/src/test/java/com/example/InvokeService.java

@@ -17,7 +17,7 @@
 package com.example;
 
 import static org.springframework.restdocs.RestDocumentation.document;
-import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.restdocs.RestDocumentationRequestBuilders.get;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 
 import org.springframework.http.MediaType;

docs/src/test/java/com/example/PathParameters.java

@@ -0,0 +1,41 @@
+/*
+ * 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 com.example;
+
+import static org.springframework.restdocs.RestDocumentation.document;
+import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
+import static org.springframework.restdocs.RestDocumentationRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+import org.springframework.test.web.servlet.MockMvc;
+
+public class PathParameters {
+
+	private MockMvc mockMvc;
+
+	public void pathParameters() throws Exception {
+		// tag::path-parameters[]
+		this.mockMvc.perform(get("/locations/{latitude}/{longitude}", 51.5072, 0.1275)) // <1>
+			.andExpect(status().isOk())
+			.andDo(document("locations").withPathParameters( // <2>
+					parameterWithName("latitude").description("The location's latitude"), // <3>
+					parameterWithName("longitude").description("The location's longitude") // <4>
+			));
+		// end::path-parameters[]
+	}
+
+}

docs/src/test/java/com/example/Payload.java

@@ -20,8 +20,8 @@ import static org.springframework.restdocs.RestDocumentation.document;
 import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
 import static org.springframework.restdocs.snippet.Attributes.attributes;
 import static org.springframework.restdocs.snippet.Attributes.key;
-import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
-import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.restdocs.RestDocumentationRequestBuilders.get;
+import static org.springframework.restdocs.RestDocumentationRequestBuilders.post;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 
 import org.springframework.http.MediaType;

docs/src/test/java/com/example/QueryParameters.java

@@ -18,7 +18,7 @@ package com.example;
 
 import static org.springframework.restdocs.RestDocumentation.document;
 import static org.springframework.restdocs.request.RequestDocumentation.parameterWithName;
-import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.restdocs.RestDocumentationRequestBuilders.get;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 
 import org.springframework.test.web.servlet.MockMvc;

docs/src/test/java/com/example/ResponsePostProcessing.java

@@ -17,7 +17,7 @@
 package com.example;
 
 import static org.springframework.restdocs.RestDocumentation.modifyResponseTo;
-import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.restdocs.RestDocumentationRequestBuilders.get;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 
 import org.springframework.test.web.servlet.MockMvc;