Include request’s path (without query string) in path parameters snippet

The ordering of parameters in the path is important so, without seeing
the path and the order in which the parameters appear, documentation for
the individual parameters is of limited use.

This commit enhances the path parameters snippet to include the
request’s path, minus any query string, in the snippet. By default,
the path is rendered as the title of the parameters table. As with
other snippets, this can be customized by providing a custom template
for the snippet.

Closes gh-103

spring-restdocs/src/main/java/org/springframework/restdocs/request/PathParametersSnippet.java

@@ -16,6 +16,7 @@
 
 package org.springframework.restdocs.request;
 
+import java.io.IOException;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
@@ -46,6 +47,21 @@ class PathParametersSnippet extends AbstractParametersSnippet {
 		super("path-parameters", attributes, descriptors);
 	}
 
+	@Override
+	protected Map<String, Object> document(MvcResult result) throws IOException {
+		Map<String, Object> model = super.document(result);
+		model.put("path", remoteQueryStringIfPresent(extractUrlTemplate(result)));
+		return model;
+	}
+
+	private String remoteQueryStringIfPresent(String urlTemplate) {
+		int index = urlTemplate.indexOf('?');
+		if (index == -1) {
+			return urlTemplate;
+		}
+		return urlTemplate.substring(0, index);
+	}
+
 	@Override
 	protected Set<String> extractActualParameters(MvcResult result) {
 		String urlTemplate = extractUrlTemplate(result);

spring-restdocs/src/main/resources/org/springframework/restdocs/templates/default-path-parameters.snippet

@@ -1,3 +1,4 @@
+.{{path}}
 |===
 |Parameter|Description
 

spring-restdocs/src/test/java/org/springframework/restdocs/request/PathParametersSnippetTests.java

@@ -24,6 +24,7 @@ import static org.springframework.restdocs.request.RequestDocumentation.paramete
 import static org.springframework.restdocs.snippet.Attributes.attributes;
 import static org.springframework.restdocs.snippet.Attributes.key;
 import static org.springframework.restdocs.test.SnippetMatchers.tableWithHeader;
+import static org.springframework.restdocs.test.SnippetMatchers.tableWithTitleAndHeader;
 import static org.springframework.restdocs.test.StubMvcResult.result;
 import static org.springframework.restdocs.test.TestRequestBuilders.get;
 
@@ -89,8 +90,8 @@ public class PathParametersSnippetTests {
 	@Test
 	public void pathParameters() throws IOException {
 		this.snippet.expectPathParameters("path-parameters").withContents(
-				tableWithHeader("Parameter", "Description").row("a", "one").row("b",
-						"two"));
+				tableWithTitleAndHeader("/{a}/{b}", "Parameter", "Description").row("a",
+						"one").row("b", "two"));
 		new PathParametersSnippet(Arrays.asList(
 				parameterWithName("a").description("one"), parameterWithName("b")
 						.description("two"))).document(
@@ -100,6 +101,21 @@ public class PathParametersSnippetTests {
 						new RestDocumentationContext(null))));
 	}
 
+	@Test
+	public void pathParametersWithQueryString() throws IOException {
+		this.snippet.expectPathParameters("path-parameters-with-query-string")
+				.withContents(
+						tableWithTitleAndHeader("/{a}/{b}", "Parameter", "Description")
+								.row("a", "one").row("b", "two"));
+		new PathParametersSnippet(Arrays.asList(
+				parameterWithName("a").description("one"), parameterWithName("b")
+						.description("two"))).document(
+				"path-parameters-with-query-string",
+				result(get("/{a}/{b}?foo=bar", "alpha", "banana").requestAttr(
+						RestDocumentationContext.class.getName(),
+						new RestDocumentationContext(null))));
+	}
+
 	@Test
 	public void pathParametersWithCustomDescriptorAttributes() throws IOException {
 		this.snippet.expectPathParameters(

spring-restdocs/src/test/java/org/springframework/restdocs/test/SnippetMatchers.java

@@ -44,8 +44,13 @@ public class SnippetMatchers {
 		return new SnippetMatcher();
 	}
 
+	public static AsciidoctorTableMatcher tableWithTitleAndHeader(String title,
+			String... headers) {
+		return new AsciidoctorTableMatcher(title, headers);
+	}
+
 	public static AsciidoctorTableMatcher tableWithHeader(String... headers) {
-		return new AsciidoctorTableMatcher(headers);
+		return new AsciidoctorTableMatcher(null, headers);
 	}
 
 	public static HttpRequestMatcher httpRequest(RequestMethod method, String uri) {
@@ -166,7 +171,10 @@ public class SnippetMatchers {
 
 	public static class AsciidoctorTableMatcher extends AbstractSnippetContentMatcher {
 
-		private AsciidoctorTableMatcher(String... columns) {
+		private AsciidoctorTableMatcher(String title, String... columns) {
+			if (StringUtils.hasText(title)) {
+				this.addLine("." + title);
+			}
 			this.addLine("|===");
 			String header = "|"
 					+ StringUtils