Issue #248 Add a curl request example

openapi2markup/src/main/resources/io/github/swagger2markup/config/default.properties

@@ -1,6 +1,5 @@
 swagger2markup.markupLanguage=ASCIIDOC
 swagger2markup.swaggerMarkupLanguage=ASCIIDOC
-swagger2markup.generatedExamplesEnabled=false
 swagger2markup.hostnameEnabled=false
 swagger2markup.basePathPrefixEnabled=false
 swagger2markup.operationExtensionsEnabled=false
@@ -28,3 +27,17 @@ swagger2markup.responseOrderBy=NATURAL
 swagger2markup.listDelimiterEnabled=false
 swagger2markup.listDelimiter=,
 swagger2markup.asciidoc.pegdown.timeoutMillis=2000
+
+swagger2markup.generatedExamplesEnabled=false
+# basic, curl, invoke-webrequest
+swagger2markup.requestExamplesFormat=basic
+# default, bash, powershell, etc.
+swagger2markup.requestExamplesSourceFormat=default
+# hide, inherit or hostname
+swagger2markup.requestExamplesHost=hide
+# hide, inherit or schema (e.g. https, https, etc.)
+swagger2markup.requestExamplesSchema=hide
+swagger2markup.requestExamplesHideBasePath=true
+swagger2markup.requestExamplesIncludeAllQueryParams=false
+# single, commaSeparated, multiple, multiple[]
+swagger2markup.requestExamplesQueryArrayStyle=single

swagger2markup-core/src/main/java/io/github/swagger2markup/Schema2MarkupProperties.java

@@ -36,6 +36,13 @@ public class Schema2MarkupProperties {
      */
     public static final String PROPERTIES_PREFIX = "swagger2markup";
 
+    public static final String REQUEST_EXAMPLES_FORMAT = PROPERTIES_PREFIX + ".requestExamplesFormat";
+    public static final String REQUEST_EXAMPLES_SOURCE_FORMAT = PROPERTIES_PREFIX + ".requestExamplesSourceFormat";
+    public static final String REQUEST_EXAMPLES_HOST = PROPERTIES_PREFIX + ".requestExamplesHost";
+    public static final String REQUEST_EXAMPLES_SCHEMA = PROPERTIES_PREFIX + ".requestExamplesSchema";
+    public static final String REQUEST_EXAMPLES_HIDE_BASE_PATH = PROPERTIES_PREFIX + ".requestExamplesHideBasePath";
+    public static final String REQUEST_EXAMPLES_QUERY_ARRAY_STYLE = PROPERTIES_PREFIX +".requestExamplesQueryArrayStyle";
+    public static final String REQUEST_EXAMPLES_INCLUDE_ALL_QUERY_PARAMS = PROPERTIES_PREFIX + ".requestExamplesIncludeAllQueryParams";
     public static final String MARKUP_LANGUAGE = PROPERTIES_PREFIX + ".markupLanguage";
     public static final String SWAGGER_MARKUP_LANGUAGE = PROPERTIES_PREFIX + ".swaggerMarkupLanguage";
     public static final String GENERATED_EXAMPLES_ENABLED = PROPERTIES_PREFIX + ".generatedExamplesEnabled";

swagger2markup-core/src/main/java/io/github/swagger2markup/config/Schema2MarkupConfig.java

@@ -309,4 +309,55 @@ public interface Schema2MarkupConfig {
      * @return custom timeout value
      */
     int getAsciidocPegdownTimeoutMillis();
+
+    /**
+     * Returns format name which should be used to format request example string.
+     *
+     * @return `basic`, `curl` or `invoke-webrequest`
+     */
+    String getRequestExamplesFormat();
+
+    /**
+     * Returns format name which should be used to highlight source block with request example string
+     *
+     * @return any string or `default`
+     */
+    String getRequestExamplesSourceFormat();
+
+    /**
+     * Should we output optional query params in source block with request example string
+     *
+     * @return false if example request should contain only required params
+     */
+    boolean getRequestExamplesIncludeAllQueryParams();
+
+    /**
+     * How we should output array query params:
+     *
+     * @return `single` —  single time (similar to basic types), `commaSeparated` — single time with multiple comma
+     * separated values, `multiple` times with same param name and different values, `multiple[]` times with array
+     * brackets as param name suffix.
+     */
+    String getRequestExamplesQueryArrayStyle();
+
+    /**
+     * Should we hide, inherit or override hostname (e.g. with google.com) from  yml file
+     *
+     * @return `hide`, `inherit` or string with hostname to be used in request example
+     */
+    String getRequestExamplesHost();
+
+    /**
+     * Should we hide, inherit or override schema (http, https name it) from yml file
+     *
+     * @return `hide`, `inherit` or string with schema name to be used in request example
+     */
+    String getRequestExamplesSchema();
+
+    /**
+     * Should we hide or show base path in example request endpoint address
+     *
+     * @return true or false
+     */
+    boolean getRequestExamplesHideBasePath();
 }

swagger2markup-core/src/main/java/io/github/swagger2markup/config/builder/Schema2MarkupConfigBuilder.java

@@ -69,6 +69,13 @@ public Schema2MarkupConfigBuilder(Schema2MarkupProperties schema2MarkupPropertie
             ((AbstractConfiguration) configuration).setListDelimiterHandler(new DefaultListDelimiterHandler(config.listDelimiter));
         }
 
+        config.requestExamplesFormat = schema2MarkupProperties.getRequiredString(REQUEST_EXAMPLES_FORMAT);
+        config.requestExamplesSourceFormat = schema2MarkupProperties.getRequiredString(REQUEST_EXAMPLES_SOURCE_FORMAT);
+        config.requestExamplesHost = schema2MarkupProperties.getRequiredString(REQUEST_EXAMPLES_HOST);
+        config.requestExamplesSchema = schema2MarkupProperties.getRequiredString(REQUEST_EXAMPLES_SCHEMA);
+        config.requestExamplesHideBasePath = schema2MarkupProperties.getRequiredBoolean(REQUEST_EXAMPLES_HIDE_BASE_PATH);
+        config.requestExamplesQueryArrayStyle = schema2MarkupProperties.getRequiredString(REQUEST_EXAMPLES_QUERY_ARRAY_STYLE);
+        config.requestExamplesIncludeAllQueryParams = schema2MarkupProperties.getRequiredBoolean(REQUEST_EXAMPLES_INCLUDE_ALL_QUERY_PARAMS);
         config.markupLanguage = schema2MarkupProperties.getRequiredMarkupLanguage(MARKUP_LANGUAGE);
         config.schemaMarkupLanguage = schema2MarkupProperties.getRequiredMarkupLanguage(SWAGGER_MARKUP_LANGUAGE);
         config.generatedExamplesEnabled = schema2MarkupProperties.getRequiredBoolean(GENERATED_EXAMPLES_ENABLED);
@@ -537,6 +544,91 @@ public Schema2MarkupConfigBuilder withLineSeparator(LineSeparator lineSeparator)
         return this;
     }
 
+    /**
+     * Specifies the request examples format to use.
+     *
+     * @param requestExamplesFormat `basic`, `curl` or `invoke-webrequest`
+     * @return this builder
+     */
+    public Schema2MarkupConfigBuilder withRequestExamplesFormat(String requestExamplesFormat) {
+        Validate.notNull(requestExamplesFormat, "%s must not be null", requestExamplesFormat);
+        config.requestExamplesFormat = requestExamplesFormat;
+        return this;
+    }
+
+    /**
+     * format name which should be used to highlight source block with request example string
+     *
+     * @param requestExamplesSourceFormat any string or `default`
+     * @return this builder
+     */
+    public Schema2MarkupConfigBuilder withRequestExamplesSourceFormat(String requestExamplesSourceFormat) {
+        Validate.notNull(requestExamplesSourceFormat, "%s must not be null", requestExamplesSourceFormat);
+        config.requestExamplesSourceFormat = requestExamplesSourceFormat;
+        return this;
+    }
+
+    /**
+     * Should we hide, inherit or override hostname (e.g. with google.com) from  yml file
+     *
+     * @param requestExamplesHost  `hide`, `inherit` or string with hostname to be used in request example
+     * @return this builder
+     */
+    public Schema2MarkupConfigBuilder withRequestExamplesHost(String requestExamplesHost) {
+        Validate.notNull(requestExamplesHost, "%s must not ber null", requestExamplesHost);
+        config.requestExamplesHost = requestExamplesHost;
+        return this;
+    }
+
+    /**
+     * Should we hide, inherit or override schema (http, https name it) from yml file
+     *
+     * @param requestExamplesSchema `hide`, `inherit` or string with schema name to be used in request example
+     * @return this builder
+     */
+    public Schema2MarkupConfigBuilder withRequestExamplesSchema(String requestExamplesSchema) {
+        Validate.notNull(requestExamplesSchema, "%s must not be null", requestExamplesSchema);
+        config.requestExamplesSchema = requestExamplesSchema;
+        return this;
+    }
+
+    /**
+     * Should we hide or show base path in example request endpoint address
+     *
+     * @param requestExamplesHideBasePath true or false
+     * @return this builder
+     * @throws PatternSyntaxException when pattern cannot be compiled
+     */
+    public Schema2MarkupConfigBuilder withRequestExamplesHideBasePath(boolean requestExamplesHideBasePath) {
+        config.requestExamplesHideBasePath = requestExamplesHideBasePath;
+        return this;
+    }
+
+    /**
+     * Should we output optional query params in source block with request example string
+     *
+     * @param requestExamplesIncludeAllQueryParams false if example request should contain only required params
+     * @return this builder
+     */
+    public Schema2MarkupConfigBuilder withRequestExamplesIncludeAllQueryParams(boolean requestExamplesIncludeAllQueryParams) {
+        config.requestExamplesIncludeAllQueryParams = requestExamplesIncludeAllQueryParams;
+        return this;
+    }
+
+    /**
+     * How we should output array query params
+     *
+     * @param requestExamplesQueryArrayStyle `single` —  single time (similar to basic types), `commaSeparated` — single time with multiple comma
+     *      separated values, `multiple` times with same param name and different values, `multiple[]` times with array
+     *      brackets as param name suffix.
+     * @return this builder
+     */
+    public Schema2MarkupConfigBuilder withRequestExamplesQueryArrayStyle(String requestExamplesQueryArrayStyle) {
+        Validate.notNull(requestExamplesQueryArrayStyle, "%s must not be null", requestExamplesQueryArrayStyle);
+        config.requestExamplesQueryArrayStyle = requestExamplesQueryArrayStyle;
+        return this;
+    }
+
     protected static CompositeConfiguration getCompositeConfiguration(Configuration configuration) {
         CompositeConfiguration compositeConfiguration = new CompositeConfiguration();
         compositeConfiguration.addConfiguration(new SystemConfiguration());
@@ -552,6 +644,15 @@ public static class DefaultSchema2MarkupConfig implements Schema2MarkupConfig {
         private MarkupLanguage markupLanguage;
         private MarkupLanguage schemaMarkupLanguage;
         private boolean generatedExamplesEnabled;
+
+        private String requestExamplesFormat;
+        private String requestExamplesSourceFormat;
+        private String requestExamplesHost;
+        private String requestExamplesSchema;
+        private boolean requestExamplesHideBasePath;
+        private boolean requestExamplesIncludeAllQueryParams;
+        private String requestExamplesQueryArrayStyle;
+
         private boolean hostnameEnabled;
         private boolean basePathPrefixEnabled;
         private boolean separatedDefinitionsEnabled;
@@ -793,5 +894,39 @@ public List<PageBreakLocations> getPageBreakLocations() {
         public int getAsciidocPegdownTimeoutMillis() {
             return asciidocPegdownTimeoutMillis;
         }
+
+        @Override
+        public String getRequestExamplesFormat() {
+            return requestExamplesFormat;
+        }
+
+        @Override
+        public String getRequestExamplesSourceFormat() {
+            return requestExamplesSourceFormat;
+        }
+
+        @Override
+        public boolean getRequestExamplesIncludeAllQueryParams() {
+            return requestExamplesIncludeAllQueryParams;
+        }
+
+        @Override
+        public String getRequestExamplesQueryArrayStyle() {
+            return requestExamplesQueryArrayStyle;
+        }
+
+        @Override
+        public String getRequestExamplesHost() {
+            return requestExamplesHost;
+        }
+
+        @Override
+        public String getRequestExamplesSchema() {
+            return requestExamplesSchema;
+        }
+        @Override
+        public boolean getRequestExamplesHideBasePath() {
+            return requestExamplesHideBasePath;
+        }
     }
-}
+}

swagger2markup-documentation/src/docs/asciidoc/usage_guide.adoc

@@ -7,14 +7,14 @@ Swagger2Markup converts a Swagger JSON or YAML specification into either **Ascii
 
 ==== Conversion of a local Swagger file
 
-The entry point of the Swagger2Markup API is the ``Swagger2MarkupConverter`` class. This class provides static factory methods to create a `Swagger2MarkupConverter.Builder`. 
+The entry point of the Swagger2Markup API is the ``Swagger2MarkupConverter`` class. This class provides static factory methods to create a `Swagger2MarkupConverter.Builder`.
 
 [source,java,indent=0]
 ----
 include::{coreProjectDir}/src/test/java/io/github/swagger2markup/DocumentationTest.java[tags=localSwaggerSpec]
 ----
 
-1.  Create a ``Swagger2MarkupConverter.Builder`` by specifying the Path to the local file 
+1.  Create a ``Swagger2MarkupConverter.Builder`` by specifying the Path to the local file
 2.  Build an instance of the ``Swagger2MarkupConverter``
 3.  Invoke ``toFolder`` by specifying the output directory
 
@@ -139,7 +139,6 @@ The following tables list all available properties of Swagger2Markup:
 |swagger2markup.pathsGroupedBy| Specifies how the paths should be grouped | AS_IS, TAGS, REGEX | AS_IS
 |swagger2markup.outputLanguage| Specifies the language of the labels | EN, DE, FR, RU | EN
 |swagger2markup.lineSeparator| Specifies the line separator which should be used | UNIX, WINDOWS, MAC | <System-dependent>
-|swagger2markup.generatedExamplesEnabled| Specifies if HTTP request and response examples should be generated | true, false | false
 |swagger2markup.flatBodyEnabled| Optionally isolate the body parameter, if any, from other parameters | true, false | false
 |swagger2markup.pathSecuritySectionEnabled| Optionally disable the security section for path sections | true, false | true
 |swagger2markup.anchorPrefix| Optionally prefix all anchors for uniqueness if you want to include generated documents into a global documentation | Any String |
@@ -184,7 +183,7 @@ The following tables list all available properties of Swagger2Markup:
 |===
 |Name | Description |  Possible Values | Default
 |swagger2markup.interDocumentCrossReferencesEnabled| Enable use of inter-document cross-references when needed | true, false | false
-|swagger2markup.interDocumentCrossReferencesPrefix| Specifies a prefix for all inter-document cross-references for advanced usage | Any String | 
+|swagger2markup.interDocumentCrossReferencesPrefix| Specifies a prefix for all inter-document cross-references for advanced usage | Any String |
 |===
 
 [options="header"]
@@ -201,6 +200,59 @@ The following tables list all available properties of Swagger2Markup:
 |swagger2markup.pageBreakLocations | Specifies where page breaks should be inserted. | BEFORE_OPERATION, BEFORE_OPERATION_DESCRIPTION, BEFORE_OPERATION_PARAMETERS, BEFORE_OPERATION_RESPONSES, BEFORE_OPERATION_CONSUMES, BEFORE_OPERATION_PRODUCES, BEFORE_OPERATION_EXAMPLE_REQUEST, BEFORE_OPERATION_EXAMPLE_RESPONSE, BEFORE_DEFINITION, AFTER_OPERATION, AFTER_OPERATION_DESCRIPTION, AFTER_OPERATION_PARAMETERS, AFTER_OPERATION_RESPONSES, AFTER_OPERATION_CONSUMES, AFTER_OPERATION_PRODUCES, AFTER_OPERATION_EXAMPLE_REQUEST, AFTER_OPERATION_EXAMPLE_RESPONSE, AFTER_DEFINITION | empty
 |===
 
+
+[options="header"]
+.Properties which configure examples generation
+|===
+|Name |Description |Possible Values |Default
+
+|swagger2markup.generatedExamplesEnabled
+| Specifies if HTTP request and response examples should be generated
+| true, false
+| false
+
+|swagger2markup.requestExamplesFormat
+| Specifies if `Request path` contents in `Example HTTP request` section should contain popular example utility
+invocation, e.g. `curl`
+a|
+* `basic` — example will have only endpoint and query params
+* `curl` — example with `curl` utility
+* `invoke-webrequest` — example with `Invoke-WebRequest` command of `powershell`
+| basic
+
+|swagger2markup.requestExamplesSourceFormat
+|`Request path` source block code style format
+| `default` or any suppordet by asciidoc
+| none for `basic`, `bash` for `curl` and `powershell` for `WebRequest`
+
+|swagger2markup.requestExamplesIncludeAllQueryParams
+|Specifies if `Request path` should contain required and optional params (if true) or only required (if false)
+|true, false
+|false
+
+|swagger2markup.requestExamplesHost
+|Should we hide, inherit or override hostname (e.g. with google.com) from  yml file
+|`hide`, `inherit` or string with hostname to be used in request example
+| hide
+
+|swagger2markup.requestExamplesSchema
+|Should we hide, inherit or override schema (http, https name it) from yml file
+|`hide`, `inherit` or string with schema name to be used in request example
+| hide
+
+|swagger2markup.requestExamplesHideBasePath
+|Should we hide or show base path in example request endpoint address
+|true, false
+|true
+
+|swagger2markup.requestExamplesQueryArrayStyle
+|How we should output array query params
+|`single` —  single time (similar to basic types), `commaSeparated` — single time with multiple comma separated values, `multiple` times with same param name and different values, `multiple[]` times with array brackets as param name suffix.
+|single
+
+
+|===
+
 === Logging
 
 Swagger2Markup uses http://www.slf4j.org/[SLF4J] for all internal logging, but leaves the underlying log implementation open. To change the log level, you have the set the log level of the `io.github.swagger2markup` package.