Polish "Provide more control of formatting of curl and HTTPie commands"

See gh-348
Closes gh-260

spring-restdocs-core/src/main/java/org/springframework/restdocs/cli/CliDocumentation.java

@@ -27,16 +27,17 @@ import org.springframework.restdocs.snippet.Snippet;
  * @author Andy Wilkinson
  * @author Paul-Christian Volkmer
  * @author Raman Gupta
+ * @author Tomasz Kopczynski
  * @since 1.1.0
  */
 public abstract class CliDocumentation {
 
+	static final CommandFormatter DEFAULT_COMMAND_FORMATTER = multiLineFormat();
+
 	private CliDocumentation() {
 
 	}
 
-	private static final CommandFormatter defaultCommandFormatter = multiLineFormat();
-
 	/**
 	 * Returns a new {@code Snippet} that will document the curl request for the API
 	 * operation.
@@ -44,7 +45,7 @@ public abstract class CliDocumentation {
 	 * @return the snippet that will document the curl request
 	 */
 	public static Snippet curlRequest() {
-		return curlRequest(defaultCommandFormatter);
+		return curlRequest(DEFAULT_COMMAND_FORMATTER);
 	}
 
 	/**
@@ -56,15 +57,17 @@ public abstract class CliDocumentation {
 	 * @return the snippet that will document the curl request
 	 */
 	public static Snippet curlRequest(Map<String, Object> attributes) {
-		return curlRequest(attributes, defaultCommandFormatter);
+		return curlRequest(attributes, DEFAULT_COMMAND_FORMATTER);
 	}
 
 	/**
 	 * Returns a new {@code Snippet} that will document the curl request for the API
-	 * operation. The given {@code commandFormatter} will be used for formatting the snippet.
-*
+	 * operation. The given {@code commandFormatter} will be used to format the curl
+	 * command in the snippet.
+	 *
 	 * @param commandFormatter the command formatter
 	 * @return the snippet that will document the curl request
+	 * @since 1.2.0
 	 */
 	public static Snippet curlRequest(CommandFormatter commandFormatter) {
 		return curlRequest(null, commandFormatter);
@@ -73,13 +76,16 @@ public abstract class CliDocumentation {
 	/**
 	 * Returns a new {@code Snippet} that will document the curl request for the API
 	 * operation. The given {@code attributes} will be available during snippet
-	 * generation. The given {@code commandFormatter} will be used for formatting the snippet.
+	 * generation. The given {@code commandFormatter} will be used to format the curl
+	 * command in the snippet.
 	 *
 	 * @param attributes the attributes
 	 * @param commandFormatter the command formatter
 	 * @return the snippet that will document the curl request
+	 * @since 1.2.0
 	 */
-	public static Snippet curlRequest(Map<String, Object> attributes, CommandFormatter commandFormatter) {
+	public static Snippet curlRequest(Map<String, Object> attributes,
+			CommandFormatter commandFormatter) {
 		return new CurlRequestSnippet(attributes, commandFormatter);
 	}
 
@@ -90,7 +96,7 @@ public abstract class CliDocumentation {
 	 * @return the snippet that will document the HTTPie request
 	 */
 	public static Snippet httpieRequest() {
-		return httpieRequest(defaultCommandFormatter);
+		return httpieRequest(DEFAULT_COMMAND_FORMATTER);
 	}
 
 	/**
@@ -102,47 +108,54 @@ public abstract class CliDocumentation {
 	 * @return the snippet that will document the HTTPie request
 	 */
 	public static Snippet httpieRequest(Map<String, Object> attributes) {
-		return httpieRequest(attributes, defaultCommandFormatter);
+		return httpieRequest(attributes, DEFAULT_COMMAND_FORMATTER);
 	}
 
 	/**
 	 * Returns a new {@code Snippet} that will document the HTTPie request for the API
-	 * operation. The given {@code commandFormatter} will be used for formatting the snippet.
+	 * operation. The given {@code commandFormatter} will be used to format the HTTPie
+	 * command in the snippet.
 	 *
 	 * @param commandFormatter the command formatter
 	 * @return the snippet that will document the HTTPie request
+	 * @since 1.2.0
 	 */
 	public static Snippet httpieRequest(CommandFormatter commandFormatter) {
-		return httpieRequest(null, defaultCommandFormatter);
+		return httpieRequest(null, commandFormatter);
 	}
 
 	/**
 	 * Returns a new {@code Snippet} that will document the HTTPie request for the API
 	 * operation. The given {@code attributes} will be available during snippet
-	 * generation. The given {@code commandFormatter} will be used for formatting the snippet.
+	 * generation. The given {@code commandFormatter} will be used to format the HTTPie
+	 * command in the snippet snippet.
 	 *
 	 * @param attributes the attributes
 	 * @param commandFormatter the command formatter
 	 * @return the snippet that will document the HTTPie request
+	 * @since 1.2.0
 	 */
-	public static Snippet httpieRequest(Map<String, Object> attributes, CommandFormatter commandFormatter) {
+	public static Snippet httpieRequest(Map<String, Object> attributes,
+			CommandFormatter commandFormatter) {
 		return new HttpieRequestSnippet(attributes, commandFormatter);
 	}
-	/**
-	 * Creates a new {@code CommandFormatter} which formats input to a multi line output.
-	 *
-	 * @return A multi line {@code commandFormatter}
-	 */
-	public static CommandFormatter multiLineFormat() {
-		return new ConcatenatingCommandFormatter(" \\%n ");
-	}
 
 	/**
-	 * Creates a new {@code CommandFormatter} which formats input to a single line output.
+	 * Creates a new {@code CommandFormatter} that produces multi-line output.
 	 *
-	 * @return A single line {@code CommandFormatter}
+	 * @return A multi-line {@code CommandFormatter}
+	 */
+	public static CommandFormatter multiLineFormat() {
+		return new ConcatenatingCommandFormatter(" \\%n    ");
+	}
+
+	/**
+	 * Creates a new {@code CommandFormatter} that produces single-line output.
+	 *
+	 * @return A single-line {@code CommandFormatter}
 	 */
 	public static CommandFormatter singleLineFormat() {
 		return new ConcatenatingCommandFormatter(" ");
 	}
+
 }

spring-restdocs-core/src/main/java/org/springframework/restdocs/cli/CommandFormatter.java

@@ -19,19 +19,20 @@ package org.springframework.restdocs.cli;
 import java.util.List;
 
 /**
- * Formatter for {@link CurlRequestSnippet} and {@link HttpieRequestSnippet}.
- * Its purpose is to format a command snippet from a list of its parts represented
- * as {@code String}s.
+ * Formatter for CLI commands such as those included in {@link CurlRequestSnippet} and
+ * {@link HttpieRequestSnippet}.
  *
  * @author Tomasz Kopczynski
+ * @since 1.2.0
  */
 public interface CommandFormatter {
 
 	/**
-	 * Formats a list of {@code String}s into a single {@code String}.
+	 * Formats a list of {@code elements} into a single {@code String}.
 	 *
-	 * @param elements A list of {@code String}s to be formatted
-	 * @return A list of {@code String}s formatted as one {@code String}
+	 * @param elements The {@code String} elements to be formatted
+	 * @return A single formatted {@code String}
 	 */
 	String format(List<String> elements);
+
 }

spring-restdocs-core/src/main/java/org/springframework/restdocs/cli/CurlRequestSnippet.java

@@ -39,9 +39,12 @@ import org.springframework.util.StringUtils;
  *
  * @author Andy Wilkinson
  * @author Paul-Christian Volkmer
+ * @author Tomasz Kopczynski
  * @since 1.1.0
  * @see CliDocumentation#curlRequest()
+ * @see CliDocumentation#curlRequest(CommandFormatter)
  * @see CliDocumentation#curlRequest(Map)
+ * @see CliDocumentation#curlRequest(Map, CommandFormatter)
  */
 public class CurlRequestSnippet extends TemplatedSnippet {
 
@@ -49,16 +52,19 @@ public class CurlRequestSnippet extends TemplatedSnippet {
 
 	/**
 	 * Creates a new {@code CurlRequestSnippet} with no additional attributes.
+	 *
+	 * @deprecated since 1.2.0 in favor of {@link #CurlRequestSnippet(CommandFormatter)}
 	 */
 	@Deprecated
 	protected CurlRequestSnippet() {
-		this(null, null);
+		this(null, CliDocumentation.DEFAULT_COMMAND_FORMATTER);
 	}
 
 	/**
-	 * Creates a new {@code CurlRequestSnippet} with a given {@link CommandFormatter}.
+	 * Creates a new {@code CurlRequestSnippet} that will use the given
+	 * {@code commandFormatter} to format the curl command.
 	 *
-	 * @param commandFormatter The formatter for generating the snippet
+	 * @param commandFormatter The formatter
 	 */
 	protected CurlRequestSnippet(CommandFormatter commandFormatter) {
 		this(null, commandFormatter);
@@ -69,24 +75,26 @@ public class CurlRequestSnippet extends TemplatedSnippet {
 	 * {@code attributes} that will be included in the model during template rendering.
 	 *
 	 * @param attributes The additional attributes
+	 * @deprecated since 1.2.0 in favor of
+	 * {@link #CurlRequestSnippet(Map, CommandFormatter)}
 	 */
 	@Deprecated
 	protected CurlRequestSnippet(Map<String, Object> attributes) {
-		this(attributes, null);
+		this(attributes, CliDocumentation.DEFAULT_COMMAND_FORMATTER);
 	}
 
 	/**
 	 * Creates a new {@code CurlRequestSnippet} with the given additional
-	 * {@code attributes} that will be included in the model during template rendering
-	 * and the given {@link CommandFormatter}.
+	 * {@code attributes} that will be included in the model during template rendering.
+	 * The given {@code commandFormaatter} will be used to format the curl command.
 	 *
 	 * @param attributes The additional attributes
 	 * @param commandFormatter The formatter for generating the snippet
 	 */
-	protected CurlRequestSnippet(Map<String, Object> attributes, CommandFormatter commandFormatter) {
+	protected CurlRequestSnippet(Map<String, Object> attributes,
+			CommandFormatter commandFormatter) {
 		super("curl-request", attributes);
-
-		Assert.notNull(commandFormatter, "Command formatter must be set");
+		Assert.notNull(commandFormatter, "Command formatter must not be null");
 		this.commandFormatter = commandFormatter;
 	}
 

spring-restdocs-core/src/main/java/org/springframework/restdocs/cli/HttpieRequestSnippet.java

@@ -42,6 +42,7 @@ import org.springframework.util.StringUtils;
  *
  * @author Raman Gupta
  * @author Andy Wilkinson
+ * @author Tomasz Kopczynski
  * @since 1.1.0
  * @see CliDocumentation#httpieRequest()
  * @see CliDocumentation#httpieRequest(Map)
@@ -52,6 +53,8 @@ public class HttpieRequestSnippet extends TemplatedSnippet {
 
 	/**
 	 * Creates a new {@code HttpieRequestSnippet} with no additional attributes.
+	 *
+	 * @deprecated since 1.2.0 in favor of {@link #HttpieRequestSnippet(CommandFormatter)}
 	 */
 	@Deprecated
 	protected HttpieRequestSnippet() {
@@ -59,9 +62,10 @@ public class HttpieRequestSnippet extends TemplatedSnippet {
 	}
 
 	/**
-	 * Creates a new {@code HttpieRequestSnippet} with the given {@link CommandFormatter}.
+	 * Creates a new {@code HttpieRequestSnippet} that will use the given
+	 * {@code commandFormatter} to format the HTTPie command.
 	 *
-	 * @param commandFormatter The formatter for generating the snippet
+	 * @param commandFormatter The formatter
 	 */
 	protected HttpieRequestSnippet(CommandFormatter commandFormatter) {
 		this(null, commandFormatter);
@@ -72,6 +76,8 @@ public class HttpieRequestSnippet extends TemplatedSnippet {
 	 * {@code attributes} that will be included in the model during template rendering.
 	 *
 	 * @param attributes The additional attributes
+	 * @deprecated since 1.2.0 in favor of
+	 * {@link #HttpieRequestSnippet(Map, CommandFormatter)}
 	 */
 	@Deprecated
 	protected HttpieRequestSnippet(Map<String, Object> attributes) {
@@ -80,16 +86,16 @@ public class HttpieRequestSnippet extends TemplatedSnippet {
 
 	/**
 	 * Creates a new {@code HttpieRequestSnippet} with the given additional
-	 * {@code attributes} that will be included in the model during template rendering
-	 * and the given {@link CommandFormatter}.
+	 * {@code attributes} that will be included in the model during template rendering.
+	 * The given {@code commandFormaatter} will be used to format the HTTPie command.
 	 *
 	 * @param attributes The additional attributes
 	 * @param commandFormatter The formatter for generating the snippet
 	 */
-	protected HttpieRequestSnippet(Map<String, Object> attributes, CommandFormatter commandFormatter) {
+	protected HttpieRequestSnippet(Map<String, Object> attributes,
+			CommandFormatter commandFormatter) {
 		super("httpie-request", attributes);
-
-		Assert.notNull(commandFormatter, "Command formatter must be set");
+		Assert.notNull(commandFormatter, "Command formatter must not be null");
 		this.commandFormatter = commandFormatter;
 	}
 
@@ -200,8 +206,8 @@ public class HttpieRequestSnippet extends TemplatedSnippet {
 
 	private void writeCookies(OperationRequest request, List<String> lines) {
 		for (RequestCookie cookie : request.getCookies()) {
-			lines.add(String.format("'Cookie:%s=%s'", cookie.getName(),
-					cookie.getValue()));
+			lines.add(
+					String.format("'Cookie:%s=%s'", cookie.getName(), cookie.getValue()));
 		}
 	}
 
@@ -215,8 +221,7 @@ public class HttpieRequestSnippet extends TemplatedSnippet {
 		}
 		else if (request.isPutOrPost()) {
 			writeContentUsingParameters(
-					request.getParameters().getUniqueParameters(request.getUri()),
-					lines);
+					request.getParameters().getUniqueParameters(request.getUri()), lines);
 		}
 	}
 

spring-restdocs-core/src/test/java/org/springframework/restdocs/cli/ConcatenatingCommandFormatterTests.java

@@ -29,27 +29,33 @@ import static org.junit.Assert.assertThat;
  * Tests for {@link CommandFormatter}.
  *
  * @author Tomasz Kopczynski
+ * @author Andy Wilkinson
  */
 public class ConcatenatingCommandFormatterTests {
 
-	private CommandFormatter singleLineFormat = CliDocumentation.singleLineFormat();
-
-	private static final String STR = "test";
+	private CommandFormatter singleLineFormat = new ConcatenatingCommandFormatter(" ");
 
 	@Test
-	public void noElementsTest() {
-		assertThat(this.singleLineFormat.format(Collections.<String>emptyList()), is(equalTo("")));
+	public void formattingAnEmptyListProducesAnEmptyString() {
+		assertThat(this.singleLineFormat.format(Collections.<String>emptyList()),
+				is(equalTo("")));
+	}
+
+	@Test
+	public void formattingNullProducesAnEmptyString() {
 		assertThat(this.singleLineFormat.format(null), is(equalTo("")));
-
 	}
 
 	@Test
-	public void singleElementTest() {
-		assertThat(this.singleLineFormat.format(Collections.singletonList(STR)), is(equalTo(String.format(" %s", STR))));
+	public void formattingASingleElement() {
+		assertThat(this.singleLineFormat.format(Collections.singletonList("alpha")),
+				is(equalTo(" alpha")));
 	}
 
 	@Test
-	public void twoElementsTest() {
-		assertThat(this.singleLineFormat.format(Arrays.asList(STR, STR)), is(equalTo(String.format(" %s %s", STR, STR))));
+	public void formattingMultipleElements() {
+		assertThat(this.singleLineFormat.format(Arrays.asList("alpha", "bravo")),
+				is(equalTo(String.format(" alpha bravo"))));
 	}
+
 }

spring-restdocs-core/src/test/java/org/springframework/restdocs/cli/CurlRequestSnippetTests.java

@@ -45,6 +45,7 @@ import static org.springframework.restdocs.snippet.Attributes.key;
  * @author Dmitriy Mayboroda
  * @author Jonathan Pearlin
  * @author Paul-Christian Volkmer
+ * @author Tomasz Kopczynski
  */
 @RunWith(Parameterized.class)
 public class CurlRequestSnippetTests extends AbstractSnippetTests {
@@ -256,8 +257,10 @@ public class CurlRequestSnippetTests extends AbstractSnippetTests {
 	@Test
 	public void requestWithHeadersMultiline() throws IOException {
 		this.snippets.expectCurlRequest()
-				.withContents(codeBlock("bash").content(String.format("$ curl 'http://localhost/foo' -i"
-						+ " \\%n -H 'Content-Type: application/json' \\%n -H 'a: alpha'")));
+				.withContents(codeBlock("bash")
+						.content(String.format("$ curl 'http://localhost/foo' -i \\%n"
+								+ "    -H 'Content-Type: application/json' \\%n"
+								+ "    -H 'a: alpha'")));
 		new CurlRequestSnippet(CliDocumentation.multiLineFormat())
 				.document(this.operationBuilder.request("http://localhost/foo")
 						.header(HttpHeaders.CONTENT_TYPE,
@@ -360,11 +363,9 @@ public class CurlRequestSnippetTests extends AbstractSnippetTests {
 				attributes(
 						key("title").value("curl request title")),
 				this.commandFormatter)
-				.document(
-						this.operationBuilder
+						.document(this.operationBuilder
 								.attribute(TemplateEngine.class.getName(),
-										new MustacheTemplateEngine(
-												resolver))
+										new MustacheTemplateEngine(resolver))
 								.request("http://localhost/foo").build());
 	}
 

spring-restdocs-core/src/test/java/org/springframework/restdocs/cli/HttpieRequestSnippetTests.java

@@ -46,6 +46,8 @@ import static org.springframework.restdocs.snippet.Attributes.key;
  * @author Jonathan Pearlin
  * @author Paul-Christian Volkmer
  * @author Raman Gupta
+ * @author Tomasz Kopczynski
+ *
  */
 @RunWith(Parameterized.class)
 public class HttpieRequestSnippetTests extends AbstractSnippetTests {
@@ -256,9 +258,9 @@ public class HttpieRequestSnippetTests extends AbstractSnippetTests {
 
 	@Test
 	public void requestWithHeadersMultiline() throws IOException {
-		this.snippets.expectHttpieRequest().withContents(
-				codeBlock("bash").content(String.format("$ http GET 'http://localhost/foo'"
-						+ " \\%n 'Content-Type:application/json' \\%n 'a:alpha'")));
+		this.snippets.expectHttpieRequest().withContents(codeBlock("bash")
+				.content(String.format("$ http GET 'http://localhost/foo' \\%n"
+						+ "    'Content-Type:application/json' \\%n    'a:alpha'")));
 		new HttpieRequestSnippet(CliDocumentation.multiLineFormat())
 				.document(this.operationBuilder.request("http://localhost/foo")
 						.header(HttpHeaders.CONTENT_TYPE,
@@ -279,7 +281,7 @@ public class HttpieRequestSnippetTests extends AbstractSnippetTests {
 	@Test
 	public void multipartPostWithNoSubmittedFileName() throws IOException {
 		String expectedContent = "$ http --form POST 'http://localhost/upload'"
-						+ " 'metadata'@<(echo '{\"description\": \"foo\"}')";
+				+ " 'metadata'@<(echo '{\"description\": \"foo\"}')";
 		this.snippets.expectHttpieRequest()
 				.withContents(codeBlock("bash").content(expectedContent));
 		new HttpieRequestSnippet(this.commandFormatter).document(
@@ -293,7 +295,7 @@ public class HttpieRequestSnippetTests extends AbstractSnippetTests {
 	public void multipartPostWithContentType() throws IOException {
 		// httpie does not yet support manually set content type by part
 		String expectedContent = "$ http --form POST 'http://localhost/upload'"
-						+ " 'image'@'documents/images/example.png'";
+				+ " 'image'@'documents/images/example.png'";
 		this.snippets.expectHttpieRequest()
 				.withContents(codeBlock("bash").content(expectedContent));
 		new HttpieRequestSnippet(this.commandFormatter).document(
@@ -308,7 +310,7 @@ public class HttpieRequestSnippetTests extends AbstractSnippetTests {
 	@Test
 	public void multipartPost() throws IOException {
 		String expectedContent = "$ http --form POST 'http://localhost/upload'"
-						+ " 'image'@'documents/images/example.png'";
+				+ " 'image'@'documents/images/example.png'";
 		this.snippets.expectHttpieRequest()
 				.withContents(codeBlock("bash").content(expectedContent));
 		new HttpieRequestSnippet(this.commandFormatter).document(
@@ -322,8 +324,8 @@ public class HttpieRequestSnippetTests extends AbstractSnippetTests {
 	@Test
 	public void multipartPostWithParameters() throws IOException {
 		String expectedContent = "$ http --form POST 'http://localhost/upload'"
-						+ " 'image'@'documents/images/example.png' 'a=apple' 'a=avocado'"
-						+ " 'b=banana'";
+				+ " 'image'@'documents/images/example.png' 'a=apple' 'a=avocado'"
+				+ " 'b=banana'";
 		this.snippets.expectHttpieRequest()
 				.withContents(codeBlock("bash").content(expectedContent));
 		new HttpieRequestSnippet(this.commandFormatter).document(
@@ -355,14 +357,12 @@ public class HttpieRequestSnippetTests extends AbstractSnippetTests {
 		given(resolver.resolveTemplateResource("httpie-request"))
 				.willReturn(snippetResource("httpie-request-with-title"));
 		new HttpieRequestSnippet(
-				attributes(
-						key("title").value("httpie request title")),
+				attributes(key("title")
+						.value("httpie request title")),
 				this.commandFormatter)
-				.document(
-						this.operationBuilder
+						.document(this.operationBuilder
 								.attribute(TemplateEngine.class.getName(),
-										new MustacheTemplateEngine(
-												resolver))
+										new MustacheTemplateEngine(resolver))
 								.request("http://localhost/foo").build());
 	}