From 76dd0cc5795fa39bce4651dccd30c26e17f5fd1e Mon Sep 17 00:00:00 2001 From: Andy Wilkinson Date: Tue, 18 Aug 2015 11:33:42 +0100 Subject: [PATCH] =?UTF-8?q?Include=20request=E2=80=99s=20path=20(without?= =?UTF-8?q?=20query=20string)=20in=20path=20parameters=20snippet?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../request/PathParametersSnippet.java | 16 +++++++++++++++ .../templates/default-path-parameters.snippet | 1 + .../request/PathParametersSnippetTests.java | 20 +++++++++++++++++-- .../restdocs/test/SnippetMatchers.java | 12 +++++++++-- 4 files changed, 45 insertions(+), 4 deletions(-) diff --git a/spring-restdocs/src/main/java/org/springframework/restdocs/request/PathParametersSnippet.java b/spring-restdocs/src/main/java/org/springframework/restdocs/request/PathParametersSnippet.java index 91bf624d..a8ae9d2a 100644 --- a/spring-restdocs/src/main/java/org/springframework/restdocs/request/PathParametersSnippet.java +++ b/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 document(MvcResult result) throws IOException { + Map 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 extractActualParameters(MvcResult result) { String urlTemplate = extractUrlTemplate(result); diff --git a/spring-restdocs/src/main/resources/org/springframework/restdocs/templates/default-path-parameters.snippet b/spring-restdocs/src/main/resources/org/springframework/restdocs/templates/default-path-parameters.snippet index 067e1fb8..66db3862 100644 --- a/spring-restdocs/src/main/resources/org/springframework/restdocs/templates/default-path-parameters.snippet +++ b/spring-restdocs/src/main/resources/org/springframework/restdocs/templates/default-path-parameters.snippet @@ -1,3 +1,4 @@ +.{{path}} |=== |Parameter|Description diff --git a/spring-restdocs/src/test/java/org/springframework/restdocs/request/PathParametersSnippetTests.java b/spring-restdocs/src/test/java/org/springframework/restdocs/request/PathParametersSnippetTests.java index 1ba26c2b..43ed107b 100644 --- a/spring-restdocs/src/test/java/org/springframework/restdocs/request/PathParametersSnippetTests.java +++ b/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( diff --git a/spring-restdocs/src/test/java/org/springframework/restdocs/test/SnippetMatchers.java b/spring-restdocs/src/test/java/org/springframework/restdocs/test/SnippetMatchers.java index 46eecfcd..b174cf40 100644 --- a/spring-restdocs/src/test/java/org/springframework/restdocs/test/SnippetMatchers.java +++ b/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