Spring/spring-restdocs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
See gh-348
Closes gh-260
This commit is contained in:
Andy Wilkinson
2017-02-12 21:51:17 +01:00
parent 2cb9d36ef1
commit a6d322007b
9 changed files with 164 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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(" ");
}
}

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

@@ -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);
}

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

@@ -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;
}

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

@@ -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);
}
}