Identify location where query parameter examples are generated

* Typo fixed

* ExternalDocs section will now be rendered in result document

.gitignore

@@ -6,3 +6,4 @@ build
 /.classpath
 /.project
 /.settings/
+/out/

README.adoc

@@ -27,7 +27,7 @@ image::src/docs/asciidoc/images/Swagger2Markup.PNG[]
 image::src/docs/asciidoc/images/Swagger2Markup_definitions.PNG[]
 
 == Reference documentation
-- http://swagger2markup.github.io/swagger2markup/1.1.0/[Reference Documentation]
+- http://swagger2markup.github.io/swagger2markup/1.3.1/[Reference Documentation]
 - https://github.com/Swagger2Markup/swagger2markup/blob/master/RELEASENOTES.adoc[Release notes]
 - https://github.com/Swagger2Markup/spring-swagger2markup-demo[Demo using Swagger2Markup, Spring Boot, Springfox and spring-restdocs]
 
@@ -54,6 +54,8 @@ If you’d like an enhancement to be made to Swagger2Markup, pull requests are m
 * http://www.appdirect.com/[AppDirect] -- The leading commerce platform for selling cloud services.
 * http://www.wescale.com[wescale]
 * http://taskassure.com[TaskAssure] 
+* https://www.isaac.nl[ISAAC]
+* https://www.spreadshirt.de[Spreadshirt]
 
 == License
 

RELEASENOTES.adoc

@@ -114,4 +114,21 @@
 * Issue #205: Fixed the option to influence resource ordering
 * Issue #198: Chinese chinese language encoding
 * Issue #207: Properties that start with an underscore are displayed correctly now
-* Refactored Swagger2Markup to use a Component-Based design. A document can be composed of components and components can be composed of other components.
+* Refactored Swagger2Markup to use a Component-Based design. A document can be composed of components and components can be composed of other components.
+
+== Version 1.2.0
+* Issue #214: Add page break locations
+* Issue #223: Improve example rendering
+* Issue #215: Add ability to group operations by RegEx
+* Added new configuration options: pageBreakLocations, headerRegex
+* Added new valid value for configuration headerRegex: REGEX
+* Updated markup-document-builder from 1.1.0 to 1.1.1
+
+== Version 1.3.0
+* Updated javslang from 2.0.4 to 2.0.5
+* Updated paleo-core from 0.10.1 to 0.10.2
+* Updated swagger-parser from v1.0.23 to v1.0.25
+* Decimal numbers are formatted into locale-specific strings
+
+=== Version 1.3.1
+* PR #247: Fix request path and query params example support.

build.gradle

@@ -13,8 +13,8 @@ buildscript {
     }
 }
 description = 'swagger2markup Build'
-version = '1.1.1'
-ext.releaseVersion = '1.1.0'
+version = '1.3.2-SNAPSHOT'
+ext.releaseVersion = '1.3.1'
 group = 'io.github.swagger2markup'
 
 apply plugin: 'java'
@@ -41,13 +41,13 @@ repositories {
 }
 
 dependencies {
-    compile 'io.github.swagger2markup:markup-document-builder:1.1.0'
-    compile 'io.swagger:swagger-compat-spec-parser:1.0.23'
+    compile 'io.github.swagger2markup:markup-document-builder:1.1.1'
+    compile 'io.swagger:swagger-compat-spec-parser:1.0.25'
     compile 'org.apache.commons:commons-configuration2:2.1'
     compile 'commons-beanutils:commons-beanutils:1.9.2'
     compile 'org.apache.commons:commons-collections4:4.1'
-    compile 'io.javaslang:javaslang:2.0.4'
-    compile 'ch.netzwerg:paleo-core:0.10.1'
+    compile 'io.javaslang:javaslang:2.0.5'
+    compile 'ch.netzwerg:paleo-core:0.10.2'
     testCompile 'junit:junit:4.11'
     testCompile 'org.asciidoctor:asciidoctorj:1.5.4'
     testCompile 'ch.qos.logback:logback-classic:1.1.2'
@@ -66,5 +66,5 @@ test {
 
 
 task wrapper(type: Wrapper) {
-    gradleVersion = '3.1'
+    gradleVersion = '3.3'
 }

gradle.properties

@@ -0,0 +1,2 @@
+systemProp.file.encoding=UTF-8
+systemProp.sun.jnu.encoding=UTF-8

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
-#Thu Nov 03 09:37:13 CET 2016
+#Thu Jan 05 14:27:30 CET 2017
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-3.1-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-3.3-bin.zip

gradlew

@@ -6,12 +6,30 @@
 ##
 ##############################################################################
 
-# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
-DEFAULT_JVM_OPTS=""
+# Attempt to set APP_HOME
+# Resolve links: $0 may be a link
+PRG="$0"
+# Need this for relative symlinks.
+while [ -h "$PRG" ] ; do
+    ls=`ls -ld "$PRG"`
+    link=`expr "$ls" : '.*-> \(.*\)$'`
+    if expr "$link" : '/.*' > /dev/null; then
+        PRG="$link"
+    else
+        PRG=`dirname "$PRG"`"/$link"
+    fi
+done
+SAVED="`pwd`"
+cd "`dirname \"$PRG\"`/" >/dev/null
+APP_HOME="`pwd -P`"
+cd "$SAVED" >/dev/null
 
 APP_NAME="Gradle"
 APP_BASE_NAME=`basename "$0"`
 
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS=""
+
 # Use the maximum available, or set MAX_FD != -1 to use that value.
 MAX_FD="maximum"
 
@@ -30,6 +48,7 @@ die ( ) {
 cygwin=false
 msys=false
 darwin=false
+nonstop=false
 case "`uname`" in
   CYGWIN* )
     cygwin=true
@@ -40,26 +59,11 @@ case "`uname`" in
   MINGW* )
     msys=true
     ;;
+  NONSTOP* )
+    nonstop=true
+    ;;
 esac
 
-# Attempt to set APP_HOME
-# Resolve links: $0 may be a link
-PRG="$0"
-# Need this for relative symlinks.
-while [ -h "$PRG" ] ; do
-    ls=`ls -ld "$PRG"`
-    link=`expr "$ls" : '.*-> \(.*\)$'`
-    if expr "$link" : '/.*' > /dev/null; then
-        PRG="$link"
-    else
-        PRG=`dirname "$PRG"`"/$link"
-    fi
-done
-SAVED="`pwd`"
-cd "`dirname \"$PRG\"`/" >/dev/null
-APP_HOME="`pwd -P`"
-cd "$SAVED" >/dev/null
-
 CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
 
 # Determine the Java command to use to start the JVM.
@@ -85,7 +89,7 @@ location of your Java installation."
 fi
 
 # Increase the maximum file descriptors if we can.
-if [ "$cygwin" = "false" -a "$darwin" = "false" ] ; then
+if [ "$cygwin" = "false" -a "$darwin" = "false" -a "$nonstop" = "false" ] ; then
     MAX_FD_LIMIT=`ulimit -H -n`
     if [ $? -eq 0 ] ; then
         if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then
@@ -157,4 +161,9 @@ function splitJvmOpts() {
 eval splitJvmOpts $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS
 JVM_OPTS[${#JVM_OPTS[*]}]="-Dorg.gradle.appname=$APP_BASE_NAME"
 
+# by default we should be in the correct project dir, but when run from Finder on Mac, the cwd is wrong
+if [[ "$(uname)" == "Darwin" ]] && [[ "$HOME" == "$PWD" ]]; then
+  cd "$(dirname "$0")"
+fi
+
 exec "$JAVACMD" "${JVM_OPTS[@]}" -classpath "$CLASSPATH" org.gradle.wrapper.GradleWrapperMain "$@"

gradlew.bat

@@ -8,14 +8,14 @@
 @rem Set local scope for the variables with windows NT shell
 if "%OS%"=="Windows_NT" setlocal
 
-@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
-set DEFAULT_JVM_OPTS=
-
 set DIRNAME=%~dp0
 if "%DIRNAME%" == "" set DIRNAME=.
 set APP_BASE_NAME=%~n0
 set APP_HOME=%DIRNAME%
 
+@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+set DEFAULT_JVM_OPTS=
+
 @rem Find java.exe
 if defined JAVA_HOME goto findJavaFromJavaHome
 
@@ -49,7 +49,6 @@ goto fail
 @rem Get command-line arguments, handling Windows variants
 
 if not "%OS%" == "Windows_NT" goto win9xME_args
-if "%@eval[2+2]" == "4" goto 4NT_args
 
 :win9xME_args
 @rem Slurp the command line arguments.
@@ -60,11 +59,6 @@ set _SKIP=2
 if "x%~1" == "x" goto execute
 
 set CMD_LINE_ARGS=%*
-goto execute
-
-:4NT_args
-@rem Get arguments from the 4NT Shell from JP Software
-set CMD_LINE_ARGS=%$
 
 :execute
 @rem Setup the command line

src/docs/asciidoc/license.adoc

@@ -1,6 +1,6 @@
 == License
 
-Copyright 2016 Robert Winkler
+Copyright 2017 Robert Winkler
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
 

src/docs/asciidoc/usage_guide.adoc

@@ -136,7 +136,7 @@ The following tables list all available properties of Swagger2Markup:
 |Name | Description |  Possible Values | Default
 |swagger2markup.markupLanguage| Specifies the markup language which should be used to generate the files. | ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP | ASCIIDOC
 |swagger2markup.swaggerMarkupLanguage| Specifies the markup language used in Swagger descriptions. | ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP | MARKDOWN
-|swagger2markup.pathsGroupedBy| Specifies how the paths should be grouped | AS_IS, TAGS | AS_IS
+|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
@@ -144,6 +144,7 @@ The following tables list all available properties of Swagger2Markup:
 |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 |
 |swagger2markup.basePathPrefixEnabled| Prepend the basePath to all paths | true, false | false
+|swagger2markup.headerRegex | Regular expression to use when grouping by RegEx | Any valid RegEx pattern with at least one capture group |
 |===
 
 [options="header"]
@@ -193,6 +194,13 @@ The following tables list all available properties of Swagger2Markup:
 |swagger2markup.inlineSchemaEnabled| Enable inline object schema support | true, false | true
 |===
 
+[options="header"]
+.Properties which configure page breaking
+|===
+|Name | Description | Possible Values | Default
+|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
+|===
+
 === 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.

src/main/java/io/github/swagger2markup/ExampleType.java

@@ -0,0 +1,14 @@
+package io.github.swagger2markup;
+
+/**
+ * swagger2markup (c) Duco Hosting
+ * Created by cas on 02-Oct-17.
+ */
+public enum ExampleType {
+    QUERY,
+    POST,
+    HEADER,
+    PATH,
+    BODY,
+    OTHER
+}

src/main/java/io/github/swagger2markup/GroupBy.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,5 +17,6 @@ package io.github.swagger2markup;
 
 public enum GroupBy {
     AS_IS,
-    TAGS
+    TAGS,
+    REGEX
 }

src/main/java/io/github/swagger2markup/Labels.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -44,7 +44,7 @@ public class Labels {
     public static final String FLAGS_READ_ONLY = "flags.read_only";
 
     // Overview Document
-    public static final String CONTACT_INFORMATION ="contact_information";
+    public static final String CONTACT_INFORMATION = "contact_information";
     public static final String CONTACT_NAME = "contact_name";
     public static final String CONTACT_EMAIL = "contact_email";
     public static final String LICENSE_INFORMATION = "license_information";
@@ -58,6 +58,9 @@ public class Labels {
     public static final String HOST = "host";
     public static final String BASE_PATH = "base_path";
     public static final String SCHEMES = "schemes";
+	public static final String EXTERNAL_DOCS = "external_docs";
+	public static final String EXTERNAL_DOCS_DESC = "external_docs_desc";
+	public static final String EXTERNAL_DOCS_URL = "external_docs_url";
 
     //Security Document
     public static final String SECURITY = "security";
@@ -75,12 +78,13 @@ public class Labels {
     public static final String TYPE_COLUMN = "type_column";
     public static final String POLYMORPHISM_NATURE_COMPOSITION = "polymorphism.nature.COMPOSITION";
     public static final String POLYMORPHISM_NATURE_INHERITANCE = "polymorphism.nature.INHERITANCE";
-    
+
     //Paths Document
     public static final String RESPONSE = "response";
     public static final String REQUEST = "request";
     public static final String PATHS = "paths";
     public static final String RESOURCES = "resources";
+    public static final String OPERATIONS = "operations";
     public static final String PARAMETERS = "parameters";
     public static final String BODY_PARAMETER = "body_parameter";
     public static final String RESPONSES = "responses";
@@ -103,7 +107,7 @@ public class Labels {
      * @param key the key for the desired label
      * @return the label for the given key
      */
-    public String getLabel(String key){
+    public String getLabel(String key) {
         return resourceBundle.getString(key);
     }
 }

src/main/java/io/github/swagger2markup/Language.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/io/github/swagger2markup/OrderBy.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/io/github/swagger2markup/PageBreakLocations.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2017 Robert Winkler
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.swagger2markup;
+
+public enum PageBreakLocations {
+    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
+}

src/main/java/io/github/swagger2markup/Swagger2MarkupConfig.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,6 +21,8 @@ import io.github.swagger2markup.model.PathOperation;
 import io.swagger.models.parameters.Parameter;
 
 import java.util.Comparator;
+import java.util.List;
+import java.util.regex.Pattern;
 
 /**
  * Swagger2Markup configuration interface.
@@ -78,6 +80,11 @@ public interface Swagger2MarkupConfig {
      */
     OrderBy getTagOrderBy();
 
+    /**
+     * Specifies the regex pattern used for header matching
+     */
+    Pattern getHeaderPattern();
+
     /**
      * Specifies a custom comparator function to order tags.
      */
@@ -148,10 +155,10 @@ public interface Swagger2MarkupConfig {
      */
     boolean isFlatBodyEnabled();
 
-	/**
-	 * Optionally disable the security section for path sections
-	 */
-	boolean isPathSecuritySectionEnabled();
+    /**
+     * Optionally disable the security section for path sections
+     */
+    boolean isPathSecuritySectionEnabled();
 
     /**
      * Optionally prefix all anchors for uniqueness.
@@ -207,10 +214,30 @@ public interface Swagger2MarkupConfig {
      */
     LineSeparator getLineSeparator();
 
+    /**
+     * Specifies the array element delimiter to use for multi-valued properties.
+     * @return the element delimiter if any
+     */
+    Character getListDelimiter();
+    
+    /**
+     * Optionally allow lists in property values. Uses the {{@link #getListDelimiter()} to 
+     * delimit list values.
+     * @return whether lists are converted to arrays
+     */
+    boolean isListDelimiterEnabled();
+
     /**
      * Returns properties for extensions.
      *
      * @return the extension properties
      */
     Swagger2MarkupProperties getExtensionsProperties();
+
+    /**
+     * Returns the list of page break locations
+     *
+     * @return List of PageBreakLocations
+     */
+    List<PageBreakLocations> getPageBreakLocations();
 }

src/main/java/io/github/swagger2markup/Swagger2MarkupConverter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -56,19 +56,10 @@ public class Swagger2MarkupConverter {
 
     public Swagger2MarkupConverter(Context context) {
         this.context = context;
-        this.overviewDocument =  new OverviewDocument(context);
-        this.pathsDocument =  new PathsDocument(context);
-        this.definitionsDocument =  new DefinitionsDocument(context);
-        this.securityDocument =  new SecurityDocument(context);
-    }
-
-    /**
-     * Returns the global Context
-     *
-     * @return the global Context
-     */
-    public Context getContext(){
-        return context;
+        this.overviewDocument = new OverviewDocument(context);
+        this.pathsDocument = new PathsDocument(context);
+        this.definitionsDocument = new DefinitionsDocument(context);
+        this.securityDocument = new SecurityDocument(context);
     }
 
     /**
@@ -80,17 +71,15 @@ public class Swagger2MarkupConverter {
     public static Builder from(URI swaggerUri) {
         Validate.notNull(swaggerUri, "swaggerUri must not be null");
         String scheme = swaggerUri.getScheme();
-        if(scheme != null && swaggerUri.getScheme().startsWith("http")){
+        if (scheme != null && swaggerUri.getScheme().startsWith("http")) {
             try {
                 return from(swaggerUri.toURL());
-            }
-            catch (MalformedURLException e) {
+            } catch (MalformedURLException e) {
                 throw new RuntimeException("Failed to convert URI to URL", e);
             }
-        } else if(scheme != null && swaggerUri.getScheme().startsWith("file")){
+        } else if (scheme != null && swaggerUri.getScheme().startsWith("file")) {
             return from(Paths.get(swaggerUri));
-        }
-        else {
+        } else {
             return from(URIUtils.convertUriWithoutSchemeToFileScheme(swaggerUri));
         }
     }
@@ -101,7 +90,7 @@ public class Swagger2MarkupConverter {
      * @param swaggerURL the remote URL
      * @return a Swagger2MarkupConverter
      */
-    public static Builder from(URL swaggerURL){
+    public static Builder from(URL swaggerURL) {
         Validate.notNull(swaggerURL, "swaggerURL must not be null");
         return new Builder(swaggerURL);
     }
@@ -114,11 +103,11 @@ public class Swagger2MarkupConverter {
      */
     public static Builder from(Path swaggerPath) {
         Validate.notNull(swaggerPath, "swaggerPath must not be null");
-        if(Files.notExists(swaggerPath)){
+        if (Files.notExists(swaggerPath)) {
             throw new IllegalArgumentException(String.format("swaggerPath does not exist: %s", swaggerPath));
         }
         try {
-            if(Files.isHidden(swaggerPath)){
+            if (Files.isHidden(swaggerPath)) {
                 throw new IllegalArgumentException("swaggerPath must not be a hidden file");
             }
         } catch (IOException e) {
@@ -169,12 +158,21 @@ public class Swagger2MarkupConverter {
         return new Builder(swagger);
     }
 
+    /**
+     * Returns the global Context
+     *
+     * @return the global Context
+     */
+    public Context getContext() {
+        return context;
+    }
+
     /**
      * Converts the Swagger specification into the given {@code outputDirectory}.
      *
      * @param outputDirectory the output directory path
      */
-    public void toFolder(Path outputDirectory){
+    public void toFolder(Path outputDirectory) {
         Validate.notNull(outputDirectory, "outputDirectory must not be null");
 
         context.setOutputPath(outputDirectory);
@@ -249,7 +247,7 @@ public class Swagger2MarkupConverter {
      *
      * @param outputFile the output file
      */
-    public void toFileWithoutExtension(Path outputFile){
+    public void toFileWithoutExtension(Path outputFile) {
         Validate.notNull(outputFile, "outputFile must not be null");
 
         applyOverviewDocument().writeToFileWithoutExtension(outputFile, StandardCharsets.UTF_8);
@@ -266,7 +264,7 @@ public class Swagger2MarkupConverter {
     public String toString() {
 
         StringBuilder sb = new StringBuilder();
-        sb.append(applyOverviewDocument() .toString());
+        sb.append(applyOverviewDocument().toString());
         sb.append(applyPathsDocument().toString());
         sb.append(applyDefinitionsDocument().toString());
         sb.append(applySecurityDocument().toString());
@@ -319,7 +317,7 @@ public class Swagger2MarkupConverter {
          * @param swaggerLocation the location of the Swagger source
          * @return the Swagger model
          */
-        private Swagger readSwagger(String swaggerLocation){
+        private Swagger readSwagger(String swaggerLocation) {
             Swagger swagger = new SwaggerParser().read(swaggerLocation);
             if (swagger == null) {
                 throw new IllegalArgumentException("Failed to read the Swagger source");
@@ -377,9 +375,9 @@ public class Swagger2MarkupConverter {
         private Path outputPath;
 
         public Context(Swagger2MarkupConfig config,
-                Swagger2MarkupExtensionRegistry extensionRegistry,
-                Swagger swagger,
-                URI swaggerLocation) {
+                       Swagger2MarkupExtensionRegistry extensionRegistry,
+                       Swagger swagger,
+                       URI swaggerLocation) {
             this.config = config;
             this.extensionRegistry = extensionRegistry;
             this.swagger = swagger;
@@ -407,7 +405,7 @@ public class Swagger2MarkupConverter {
             return labels;
         }
 
-        public MarkupDocBuilder createMarkupDocBuilder(){
+        public MarkupDocBuilder createMarkupDocBuilder() {
             return MarkupDocBuilders.documentBuilder(config.getMarkupLanguage(),
                     config.getLineSeparator()).withAnchorPrefix(config.getAnchorPrefix());
         }

src/main/java/io/github/swagger2markup/Swagger2MarkupExtensionRegistry.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,30 +25,35 @@ import java.util.List;
 public interface Swagger2MarkupExtensionRegistry {
     /**
      * SwaggerModelExtension extension point can be used to preprocess the Swagger model.
+     *
      * @return registered extensions extending SwaggerModelExtension extension point
      */
     List<SwaggerModelExtension> getSwaggerModelExtensions();
 
     /**
      * OverviewDocumentExtension extension point can be used to extend the overview document content.
+     *
      * @return registered extensions extending OverviewDocumentExtension extension point
      */
     List<OverviewDocumentExtension> getOverviewDocumentExtensions();
 
     /**
      * DefinitionsDocumentExtension extension point can be used to extend the definitions document content.
+     *
      * @return registered extensions extending DefinitionsDocumentExtension extension point
      */
     List<DefinitionsDocumentExtension> getDefinitionsDocumentExtensions();
 
     /**
      * SecurityContentExtension extension point can be used to extend the security document content.
+     *
      * @return registered extensions extending SecurityContentExtension extension point
      */
     List<SecurityDocumentExtension> getSecurityDocumentExtensions();
 
     /**
      * PathsDocumentExtension extension point can be used to extend the paths document content.
+     *
      * @return registered extensions extending PathsDocumentExtension extension point
      */
     List<PathsDocumentExtension> getPathsDocumentExtensions();

src/main/java/io/github/swagger2markup/Swagger2MarkupProperties.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,18 +17,18 @@ package io.github.swagger2markup;
 
 import io.github.swagger2markup.markup.builder.MarkupLanguage;
 import io.github.swagger2markup.utils.URIUtils;
+
 import org.apache.commons.collections4.IteratorUtils;
 import org.apache.commons.configuration2.Configuration;
 import org.apache.commons.configuration2.ConfigurationConverter;
 import org.apache.commons.configuration2.MapConfiguration;
+import org.apache.commons.configuration2.ex.ConversionException;
 
 import java.net.URI;
 import java.nio.file.Path;
 import java.nio.file.Paths;
-import java.util.List;
-import java.util.Map;
-import java.util.Optional;
-import java.util.Properties;
+import java.util.*;
+import java.util.regex.Pattern;
 
 public class Swagger2MarkupProperties {
 
@@ -44,13 +44,16 @@ public class Swagger2MarkupProperties {
     public static final String SEPARATED_DEFINITIONS_ENABLED = PROPERTIES_PREFIX + ".separatedDefinitionsEnabled";
     public static final String SEPARATED_OPERATIONS_ENABLED = PROPERTIES_PREFIX + ".separatedOperationsEnabled";
     public static final String PATHS_GROUPED_BY = PROPERTIES_PREFIX + ".pathsGroupedBy";
+    public static final String HEADER_REGEX = PROPERTIES_PREFIX + ".headerRegex";
     public static final String OUTPUT_LANGUAGE = PROPERTIES_PREFIX + ".outputLanguage";
     public static final String INLINE_SCHEMA_ENABLED = PROPERTIES_PREFIX + ".inlineSchemaEnabled";
     public static final String INTER_DOCUMENT_CROSS_REFERENCES_ENABLED = PROPERTIES_PREFIX + ".interDocumentCrossReferencesEnabled";
     public static final String INTER_DOCUMENT_CROSS_REFERENCES_PREFIX = PROPERTIES_PREFIX + ".interDocumentCrossReferencesPrefix";
     public static final String FLAT_BODY_ENABLED = PROPERTIES_PREFIX + ".flatBodyEnabled";
-	public static final String PATH_SECURITY_SECTION_ENABLED = PROPERTIES_PREFIX + ".pathSecuritySectionEnabled";
+    public static final String PATH_SECURITY_SECTION_ENABLED = PROPERTIES_PREFIX + ".pathSecuritySectionEnabled";
     public static final String ANCHOR_PREFIX = PROPERTIES_PREFIX + ".anchorPrefix";
+    public static final String LIST_DELIMITER = PROPERTIES_PREFIX + ".listDelimiter";
+    public static final String LIST_DELIMITER_ENABLED = PROPERTIES_PREFIX + ".listDelimiterEnabled";
     public static final String OVERVIEW_DOCUMENT = PROPERTIES_PREFIX + ".overviewDocument";
     public static final String PATHS_DOCUMENT = PROPERTIES_PREFIX + ".pathsDocument";
     public static final String DEFINITIONS_DOCUMENT = PROPERTIES_PREFIX + ".definitionsDocument";
@@ -64,6 +67,7 @@ public class Swagger2MarkupProperties {
     public static final String PROPERTY_ORDER_BY = PROPERTIES_PREFIX + ".propertyOrderBy";
     public static final String RESPONSE_ORDER_BY = PROPERTIES_PREFIX + ".responseOrderBy";
     public static final String LINE_SEPARATOR = PROPERTIES_PREFIX + ".lineSeparator";
+    public static final String PAGE_BREAK_LOCATIONS = PROPERTIES_PREFIX + ".pageBreakLocations";
 
     /**
      * Prefix for Swagger2Markup extension properties
@@ -80,63 +84,63 @@ public class Swagger2MarkupProperties {
         this(new MapConfiguration(map));
     }
 
-    public Swagger2MarkupProperties(Configuration configuration){
+    public Swagger2MarkupProperties(Configuration configuration) {
         this.configuration = configuration;
     }
 
     /**
      * Returns an optional String property value associated with the given key.
-     * @param key the property name to resolve
      *
+     * @param key the property name to resolve
      * @return The string property
      */
-    public Optional<String> getString(String key){
+    public Optional<String> getString(String key) {
         return Optional.ofNullable(configuration.getString(key));
     }
 
     /**
      * Return the String property value associated with the given key, or
      * {@code defaultValue} if the key cannot be resolved.
-     * @param key the property name to resolve
-     * @param defaultValue the default value to return if no value is found
      *
+     * @param key          the property name to resolve
+     * @param defaultValue the default value to return if no value is found
      * @return The string property
      */
-    public String getString(String key, String defaultValue){
+    public String getString(String key, String defaultValue) {
         return configuration.getString(key, defaultValue);
     }
 
     /**
      * Return the int property value associated with the given key, or
      * {@code defaultValue} if the key cannot be resolved.
-     * @param key the property name to resolve
-     * @param defaultValue the default value to return if no value is found
      *
+     * @param key          the property name to resolve
+     * @param defaultValue the default value to return if no value is found
      * @return The int property
      */
-    public int getInt(String key, int defaultValue){
+    public int getInt(String key, int defaultValue) {
         return configuration.getInt(key, defaultValue);
     }
 
     /**
      * Returns an optional Integer property value associated with the given key.
-     * @param key the property name to resolve
      *
+     * @param key the property name to resolve
      * @return An optional Integer property
      */
-    public Optional<Integer> getInteger(String key){
+    public Optional<Integer> getInteger(String key) {
         return Optional.ofNullable(configuration.getInteger(key, null));
     }
 
     /**
      * Return the int property value associated with the given key (never {@code null}).
-     * @throws IllegalStateException if the key cannot be
      *
      * @return The int property
+     * @throws IllegalStateException if the key cannot be
      */
-    public int getRequiredInt(String key){
+    public int getRequiredInt(String key) {
         Optional<Integer> value = getInteger(key);
-        if(value.isPresent()){
+        if (value.isPresent()) {
             return value.get();
         }
         throw new IllegalStateException(String.format("required key [%s] not found", key));
@@ -144,15 +148,15 @@ public class Swagger2MarkupProperties {
 
     /**
      * Return the boolean property value associated with the given key (never {@code null}).
-     * @throws IllegalStateException if the key cannot be resolved
      *
      * @return The boolean property
+     * @throws IllegalStateException if the key cannot be resolved
      */
-    public boolean getRequiredBoolean(String key){
+    public boolean getRequiredBoolean(String key) {
         Boolean value = configuration.getBoolean(key, null);
-        if(value != null){
+        if (value != null) {
             return value;
-        }else{
+        } else {
             throw new IllegalStateException(String.format("required key [%s] not found", key));
         }
     }
@@ -160,43 +164,43 @@ public class Swagger2MarkupProperties {
     /**
      * Return the boolean property value associated with the given key, or
      * {@code defaultValue} if the key cannot be resolved.
-     * @param key the property name to resolve
-     * @param defaultValue the default value to return if no value is found
      *
+     * @param key          the property name to resolve
+     * @param defaultValue the default value to return if no value is found
      * @return The boolean property
      */
-    public boolean getBoolean(String key, boolean defaultValue){
+    public boolean getBoolean(String key, boolean defaultValue) {
         return configuration.getBoolean(key, defaultValue);
     }
 
     /**
      * Return the URI property value associated with the given key, or
      * {@code defaultValue} if the key cannot be resolved.
-     * @param key the property name to resolve
-     * @throws IllegalStateException if the value cannot be mapped to the enum
      *
+     * @param key the property name to resolve
      * @return The URI property
+     * @throws IllegalStateException if the value cannot be mapped to the enum
      */
-    public Optional<URI> getURI(String key){
+    public Optional<URI> getURI(String key) {
         Optional<String> property = getString(key);
-        if(property.isPresent()){
+        if (property.isPresent()) {
             return Optional.of(URIUtils.create(property.get()));
-        }else{
+        } else {
             return Optional.empty();
         }
     }
 
     /**
      * Return the URI property value associated with the given key (never {@code null}).
-     * @throws IllegalStateException if the key cannot be resolved
      *
      * @return The URI property
+     * @throws IllegalStateException if the key cannot be resolved
      */
-    public URI getRequiredURI(String key){
+    public URI getRequiredURI(String key) {
         Optional<String> property = getString(key);
-        if(property.isPresent()){
+        if (property.isPresent()) {
             return URIUtils.create(property.get());
-        }else{
+        } else {
             throw new IllegalStateException(String.format("required key [%s] not found", key));
         }
     }
@@ -204,31 +208,55 @@ public class Swagger2MarkupProperties {
     /**
      * Return the Path property value associated with the given key, or
      * {@code defaultValue} if the key cannot be resolved.
-     * @param key the property name to resolve
-     * @throws IllegalStateException if the value cannot be mapped to the enum
      *
+     * @param key the property name to resolve
      * @return The Path property
+     * @throws IllegalStateException if the value cannot be mapped to the enum
      */
-    public Optional<Path> getPath(String key){
+    public Optional<Path> getPath(String key) {
         Optional<String> property = getString(key);
-        if(property.isPresent()){
+        if (property.isPresent()) {
             return Optional.of(Paths.get(property.get()));
-        }else{
+        } else {
             return Optional.empty();
         }
     }
 
+    /**
+     * Return a list of Path property values associated with the given key, 
+     * or {@code defaultValue} if the key cannot be resolved.
+     * 
+     * @param key the property name to resolve
+     * @return The list of Path properties
+     * @throws IllegalStateException if the value cannot be mapped to an array of strings
+     */
+    public List<Path> getPathList(String key) {
+        List<Path> pathList = new ArrayList<>();
+
+        try {
+            String[] stringList = configuration.getStringArray(key);
+
+            for (String pathStr : stringList) {
+                pathList.add(Paths.get(pathStr));
+            }
+        } catch (ConversionException ce) {
+            throw new IllegalStateException(String.format("requested key [%s] is not convertable to an array", key));
+        }
+
+        return pathList;
+    }
+
     /**
      * Return the Path property value associated with the given key (never {@code null}).
-     * @throws IllegalStateException if the key cannot be resolved
      *
      * @return The Path property
+     * @throws IllegalStateException if the key cannot be resolved
      */
-    public Path getRequiredPath(String key){
+    public Path getRequiredPath(String key) {
         Optional<String> property = getString(key);
-        if(property.isPresent()){
+        if (property.isPresent()) {
             return Paths.get(property.get());
-        }else{
+        } else {
             throw new IllegalStateException(String.format("required key [%s] not found", key));
         }
     }
@@ -236,75 +264,75 @@ public class Swagger2MarkupProperties {
     /**
      * Return the MarkupLanguage property value associated with the given key, or
      * {@code defaultValue} if the key cannot be resolved.
-     * @param key the property name to resolve
      *
+     * @param key the property name to resolve
      * @return The MarkupLanguage property
      */
-    public Optional<MarkupLanguage> getMarkupLanguage(String key){
+    public Optional<MarkupLanguage> getMarkupLanguage(String key) {
         Optional<String> property = getString(key);
-        if(property.isPresent()){
+        if (property.isPresent()) {
             return Optional.of(MarkupLanguage.valueOf(property.get()));
-        }else{
+        } else {
             return Optional.empty();
         }
     }
 
     /**
      * Return the MarkupLanguage property value associated with the given key (never {@code null}).
-     * @throws IllegalStateException if the key cannot be resolved
      *
      * @return The MarkupLanguage property
+     * @throws IllegalStateException if the key cannot be resolved
      */
-    public MarkupLanguage getRequiredMarkupLanguage(String key){
+    public MarkupLanguage getRequiredMarkupLanguage(String key) {
         return MarkupLanguage.valueOf(configuration.getString(key));
     }
 
     /**
      * Return the Language property value associated with the given key, or
      * {@code defaultValue} if the key cannot be resolved.
-     * @param key the property name to resolve
      *
+     * @param key the property name to resolve
      * @return The Language property
      */
-    public Language getLanguage(String key){
+    public Language getLanguage(String key) {
         return Language.valueOf(configuration.getString(key));
     }
 
     /**
      * Return the GroupBy property value associated with the given key, or
      * {@code defaultValue} if the key cannot be resolved.
-     * @param key the property name to resolve
-     * @throws IllegalStateException if the value cannot be mapped to the enum
      *
+     * @param key the property name to resolve
      * @return The GroupBy property
+     * @throws IllegalStateException if the value cannot be mapped to the enum
      */
-    public GroupBy getGroupBy(String key){
+    public GroupBy getGroupBy(String key) {
         return GroupBy.valueOf(configuration.getString(key));
     }
 
     /**
      * Return the OrderBy property value associated with the given key, or
      * {@code defaultValue} if the key cannot be resolved.
-     * @param key the property name to resolve
-     * @throws IllegalStateException if the value cannot be mapped to the enum
      *
+     * @param key the property name to resolve
      * @return The OrderBy property
+     * @throws IllegalStateException if the value cannot be mapped to the enum
      */
-    public OrderBy getOrderBy(String key){
+    public OrderBy getOrderBy(String key) {
         return OrderBy.valueOf(configuration.getString(key));
     }
 
     /**
      * Return the String property value associated with the given key (never {@code null}).
-     * @throws IllegalStateException if the key cannot be resolved
      *
      * @return The String property
+     * @throws IllegalStateException if the key cannot be resolved
      */
-    public String getRequiredString(String key) throws IllegalStateException{
+    public String getRequiredString(String key) throws IllegalStateException {
         Optional<String> property = getString(key);
-        if(property.isPresent()){
+        if (property.isPresent()) {
             return property.get();
-        }else{
+        } else {
             throw new IllegalStateException(String.format("required key [%s] not found", key));
         }
     }
@@ -314,7 +342,7 @@ public class Swagger2MarkupProperties {
      *
      * @return the list of keys.
      */
-    public List<String> getKeys(){
+    public List<String> getKeys() {
         return IteratorUtils.toList(configuration.getKeys());
     }
 
@@ -331,10 +359,25 @@ public class Swagger2MarkupProperties {
      * interpreted - depends on a concrete implementation.
      *
      * @param prefix The prefix to test against.
-     *
      * @return the list of keys.
      */
-    public List<String> getKeys(String prefix){
+    public List<String> getKeys(String prefix) {
         return IteratorUtils.toList(configuration.getKeys(prefix));
     }
+
+    public List<PageBreakLocations> getPageBreakLocations(String key) {
+        List<PageBreakLocations> result = configuration.getList(PageBreakLocations.class, key);
+        if(result == null) result = new ArrayList<PageBreakLocations>();
+
+        return result;
+    }
+
+    public Optional<Pattern> getHeaderPattern(String key) {
+        Optional<String> property = getString(key);
+        if (property.isPresent()) {
+            return Optional.of(Pattern.compile(property.get()));
+        } else {
+            return Optional.empty();
+        }
+    }
 }

src/main/java/io/github/swagger2markup/builder/Swagger2MarkupConfigBuilder.java

@@ -1,5 +1,6 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
+ * Modified December 12 2016 by Cas Eliëns
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,41 +25,32 @@ import io.swagger.models.HttpMethod;
 import io.swagger.models.parameters.Parameter;
 import org.apache.commons.configuration2.*;
 import org.apache.commons.configuration2.builder.fluent.Configurations;
+import org.apache.commons.configuration2.convert.DefaultListDelimiterHandler;
 import org.apache.commons.configuration2.ex.ConfigurationException;
 import org.apache.commons.lang3.StringUtils;
 import org.apache.commons.lang3.Validate;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 
-import java.util.Comparator;
-import java.util.Map;
-import java.util.Optional;
-import java.util.Properties;
+import java.util.*;
+import java.util.regex.Pattern;
+import java.util.regex.PatternSyntaxException;
 
 import static io.github.swagger2markup.Swagger2MarkupProperties.*;
 
-public class Swagger2MarkupConfigBuilder  {
-
-    private static final Logger logger = LoggerFactory.getLogger(Swagger2MarkupConfigBuilder.class);
-
-    private static final String PROPERTIES_DEFAULT = "io/github/swagger2markup/config/default.properties";
+public class Swagger2MarkupConfigBuilder {
 
     static final Ordering<PathOperation> OPERATION_METHOD_NATURAL_ORDERING = Ordering
             .explicit(HttpMethod.POST, HttpMethod.GET, HttpMethod.PUT, HttpMethod.DELETE, HttpMethod.PATCH, HttpMethod.HEAD, HttpMethod.OPTIONS)
             .onResultOf(PathOperation::getMethod);
-
     static final Ordering<PathOperation> OPERATION_PATH_NATURAL_ORDERING = Ordering
             .natural()
             .onResultOf(PathOperation::getPath);
-
     static final Ordering<Parameter> PARAMETER_IN_NATURAL_ORDERING = Ordering
             .explicit("header", "path", "query", "formData", "body")
             .onResultOf(Parameter::getIn);
-
     static final Ordering<Parameter> PARAMETER_NAME_NATURAL_ORDERING = Ordering
             .natural()
             .onResultOf(Parameter::getName);
-
+    private static final String PROPERTIES_DEFAULT = "io/github/swagger2markup/config/default.properties";
     DefaultSwagger2MarkupConfig config = new DefaultSwagger2MarkupConfig();
 
     public Swagger2MarkupConfigBuilder() {
@@ -93,7 +85,7 @@ public class Swagger2MarkupConfigBuilder  {
         config.interDocumentCrossReferencesEnabled = swagger2MarkupProperties.getRequiredBoolean(INTER_DOCUMENT_CROSS_REFERENCES_ENABLED);
         config.interDocumentCrossReferencesPrefix = swagger2MarkupProperties.getString(INTER_DOCUMENT_CROSS_REFERENCES_PREFIX, null);
         config.flatBodyEnabled = swagger2MarkupProperties.getRequiredBoolean(FLAT_BODY_ENABLED);
-		config.pathSecuritySectionEnabled = swagger2MarkupProperties.getRequiredBoolean(PATH_SECURITY_SECTION_ENABLED);
+        config.pathSecuritySectionEnabled = swagger2MarkupProperties.getRequiredBoolean(PATH_SECURITY_SECTION_ENABLED);
         config.anchorPrefix = swagger2MarkupProperties.getString(ANCHOR_PREFIX, null);
         config.overviewDocument = swagger2MarkupProperties.getRequiredString(OVERVIEW_DOCUMENT);
         config.pathsDocument = swagger2MarkupProperties.getRequiredString(PATHS_DOCUMENT);
@@ -108,10 +100,23 @@ public class Swagger2MarkupConfigBuilder  {
         config.propertyOrderBy = swagger2MarkupProperties.getOrderBy(PROPERTY_ORDER_BY);
         config.responseOrderBy = swagger2MarkupProperties.getOrderBy(RESPONSE_ORDER_BY);
         Optional<String> lineSeparator = swagger2MarkupProperties.getString(LINE_SEPARATOR);
-        if(lineSeparator.isPresent() && StringUtils.isNoneBlank(lineSeparator.get())){
+        if (lineSeparator.isPresent() && StringUtils.isNoneBlank(lineSeparator.get())) {
             config.lineSeparator = LineSeparator.valueOf(lineSeparator.get());
         }
 
+        config.pageBreakLocations = swagger2MarkupProperties.getPageBreakLocations(PAGE_BREAK_LOCATIONS);
+
+        Optional<Pattern> headerPattern = swagger2MarkupProperties.getHeaderPattern(HEADER_REGEX);
+
+        config.headerPattern = headerPattern.orElse(null);
+
+        config.listDelimiterEnabled = swagger2MarkupProperties.getBoolean(LIST_DELIMITER_ENABLED, false);
+        config.listDelimiter = swagger2MarkupProperties.getString(LIST_DELIMITER, ",").charAt(0);
+
+        if (config.listDelimiterEnabled && configuration instanceof AbstractConfiguration) {
+            ((AbstractConfiguration) configuration).setListDelimiterHandler(new DefaultListDelimiterHandler(config.listDelimiter));
+        }
+
         Configuration swagger2markupConfiguration = compositeConfiguration.subset(PROPERTIES_PREFIX);
         Configuration extensionsConfiguration = swagger2markupConfiguration.subset(EXTENSION_PREFIX);
         config.extensionsProperties = new Swagger2MarkupProperties(extensionsConfiguration);
@@ -212,6 +217,29 @@ public class Swagger2MarkupConfigBuilder  {
         return this;
     }
 
+    /**
+     * Allows properties to contain a list of elements delimited by a specified character.
+     *
+     * @return this builder
+     */
+    public Swagger2MarkupConfigBuilder withListDelimiter() {
+        config.listDelimiterEnabled = true;
+        return this;
+    }
+
+    /**
+     * Specifies the list delimiter which should be used.
+     *
+     * @param delimiter the delimiter
+     * @return this builder
+     */
+    public Swagger2MarkupConfigBuilder withListDelimiter(Character delimiter) {
+        Validate.notNull(delimiter, "%s must not be null", "delimiter");
+        config.listDelimiter = delimiter;
+        config.listDelimiterEnabled = true;
+        return this;
+    }
+
 
     /**
      * Specifies if the paths should be grouped by tags or stay as-is.
@@ -225,6 +253,19 @@ public class Swagger2MarkupConfigBuilder  {
         return this;
     }
 
+    /**
+     * Specifies the regex pattern to use for grouping paths.
+     *
+     * @param headerRegex regex pattern string containing one capture group
+     * @return this builder
+     * @throws PatternSyntaxException when pattern cannot be compiled
+     */
+    public Swagger2MarkupConfigBuilder withHeaderRegex(String headerRegex) {
+        Validate.notNull(headerRegex, "%s must not be null", headerRegex);
+        config.headerPattern = Pattern.compile(headerRegex);
+        return this;
+    }
+
     /**
      * Specifies labels language of output files.
      *
@@ -452,17 +493,17 @@ public class Swagger2MarkupConfigBuilder  {
     }
 
     /**
-	 * Optionally disable the security section for path sections
-	 *
-	 * @return this builder
-	 */
-	public Swagger2MarkupConfigBuilder withoutPathSecuritySection() {
-		config.pathSecuritySectionEnabled = false;
-		return this;
-	}
+     * Optionally disable the security section for path sections
+     *
+     * @return this builder
+     */
+    public Swagger2MarkupConfigBuilder withoutPathSecuritySection() {
+        config.pathSecuritySectionEnabled = false;
+        return this;
+    }
 
     /**
-     *  Prepend the base path to all paths.
+     * Prepend the base path to all paths.
      *
      * @return this builder
      */
@@ -470,7 +511,7 @@ public class Swagger2MarkupConfigBuilder  {
         config.basePathPrefixEnabled = true;
         return this;
     }
-	
+
     /**
      * Optionally prefix all anchors for uniqueness.
      *
@@ -478,11 +519,23 @@ public class Swagger2MarkupConfigBuilder  {
      * @return this builder
      */
     public Swagger2MarkupConfigBuilder withAnchorPrefix(String anchorPrefix) {
-        Validate.notNull(anchorPrefix, "%s must no be null", "anchorPrefix");
+        Validate.notNull(anchorPrefix, "%s must not be null", "anchorPrefix");
         config.anchorPrefix = anchorPrefix;
         return this;
     }
 
+    /**
+     * Set the page break locations
+     *
+     * @param locations List of locations to create new pages
+     * @return this builder
+     */
+    public Swagger2MarkupConfigBuilder withPageBreaks(List<PageBreakLocations> locations) {
+        Validate.notNull(locations, "%s must not be null", "locations");
+        config.pageBreakLocations = locations;
+        return this;
+    }
+
     /**
      * Specifies the line separator which should be used.
      *
@@ -495,7 +548,7 @@ public class Swagger2MarkupConfigBuilder  {
         return this;
     }
 
-    static class DefaultSwagger2MarkupConfig implements Swagger2MarkupConfig{
+    static class DefaultSwagger2MarkupConfig implements Swagger2MarkupConfig {
 
         private MarkupLanguage markupLanguage;
         private MarkupLanguage swaggerMarkupLanguage;
@@ -521,7 +574,7 @@ public class Swagger2MarkupConfigBuilder  {
         private boolean interDocumentCrossReferencesEnabled;
         private String interDocumentCrossReferencesPrefix;
         private boolean flatBodyEnabled;
-		private boolean pathSecuritySectionEnabled;
+        private boolean pathSecuritySectionEnabled;
         private String anchorPrefix;
         private LineSeparator lineSeparator;
 
@@ -531,6 +584,12 @@ public class Swagger2MarkupConfigBuilder  {
         private String securityDocument;
         private String separatedOperationsFolder;
         private String separatedDefinitionsFolder;
+        private Character listDelimiter;
+        private boolean listDelimiterEnabled;
+
+        private List<PageBreakLocations> pageBreakLocations;
+
+        private Pattern headerPattern;
 
         private Swagger2MarkupProperties extensionsProperties;
 
@@ -579,6 +638,11 @@ public class Swagger2MarkupConfigBuilder  {
             return tagOrderBy;
         }
 
+        @Override
+        public Pattern getHeaderPattern() {
+            return headerPattern;
+        }
+
         @Override
         public Comparator<String> getTagOrdering() {
             return tagOrdering;
@@ -649,10 +713,10 @@ public class Swagger2MarkupConfigBuilder  {
             return flatBodyEnabled;
         }
 
-		@Override
-		public boolean isPathSecuritySectionEnabled() {
-			return pathSecuritySectionEnabled;
-		}
+        @Override
+        public boolean isPathSecuritySectionEnabled() {
+            return pathSecuritySectionEnabled;
+        }
 
         @Override
         public String getAnchorPrefix() {
@@ -694,6 +758,16 @@ public class Swagger2MarkupConfigBuilder  {
             return lineSeparator;
         }
 
+        @Override
+        public Character getListDelimiter() {
+            return listDelimiter;
+        }
+
+        @Override
+        public boolean isListDelimiterEnabled() {
+            return listDelimiterEnabled;
+        }
+
         @Override
         public Swagger2MarkupProperties getExtensionsProperties() {
             return extensionsProperties;
@@ -703,5 +777,10 @@ public class Swagger2MarkupConfigBuilder  {
         public boolean isBasePathPrefixEnabled() {
             return basePathPrefixEnabled;
         }
+
+        @Override
+        public List<PageBreakLocations> getPageBreakLocations() {
+            return pageBreakLocations;
+        }
     }
 }

src/main/java/io/github/swagger2markup/builder/Swagger2MarkupExtensionRegistryBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -71,7 +71,7 @@ public class Swagger2MarkupExtensionRegistryBuilder {
         return this;
     }
 
-    static class DefaultSwagger2MarkupExtensionRegistry implements Swagger2MarkupExtensionRegistry{
+    static class DefaultSwagger2MarkupExtensionRegistry implements Swagger2MarkupExtensionRegistry {
 
         private Context context;
 
@@ -80,27 +80,27 @@ public class Swagger2MarkupExtensionRegistryBuilder {
         }
 
         @Override
-        public List<SwaggerModelExtension> getSwaggerModelExtensions(){
+        public List<SwaggerModelExtension> getSwaggerModelExtensions() {
             return context.swaggerModelExtensions;
         }
 
         @Override
-        public List<OverviewDocumentExtension> getOverviewDocumentExtensions(){
+        public List<OverviewDocumentExtension> getOverviewDocumentExtensions() {
             return context.overviewDocumentExtensions;
         }
 
         @Override
-        public List<DefinitionsDocumentExtension> getDefinitionsDocumentExtensions(){
+        public List<DefinitionsDocumentExtension> getDefinitionsDocumentExtensions() {
             return context.definitionsDocumentExtensions;
         }
 
         @Override
-        public List<SecurityDocumentExtension> getSecurityDocumentExtensions(){
+        public List<SecurityDocumentExtension> getSecurityDocumentExtensions() {
             return context.securityDocumentExtensions;
         }
 
         @Override
-        public List<PathsDocumentExtension> getPathsDocumentExtensions(){
+        public List<PathsDocumentExtension> getPathsDocumentExtensions() {
             return context.pathsDocumentExtensions;
         }
 
@@ -117,7 +117,7 @@ public class Swagger2MarkupExtensionRegistryBuilder {
                        List<OverviewDocumentExtension> overviewDocumentExtensions,
                        List<DefinitionsDocumentExtension> definitionsDocumentExtensions,
                        List<PathsDocumentExtension> pathsDocumentExtensions,
-                       List<SecurityDocumentExtension> securityDocumentExtensions){
+                       List<SecurityDocumentExtension> securityDocumentExtensions) {
             this.swaggerModelExtensions = swaggerModelExtensions;
             this.overviewDocumentExtensions = overviewDocumentExtensions;
             this.definitionsDocumentExtensions = definitionsDocumentExtensions;

src/main/java/io/github/swagger2markup/internal/adapter/ParameterAdapter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -44,29 +44,50 @@ import static io.github.swagger2markup.internal.utils.MarkupDocBuilderUtils.*;
 public class ParameterAdapter {
 
     private final Parameter parameter;
-    private Type type;
     private final List<ObjectType> inlineDefinitions = new ArrayList<>();
     private final Swagger2MarkupConfig config;
+    private Type type;
 
     public ParameterAdapter(Swagger2MarkupConverter.Context context,
                             PathOperation operation,
                             Parameter parameter,
-                            DocumentResolver definitionDocumentResolver){
+                            DocumentResolver definitionDocumentResolver) {
         Validate.notNull(parameter, "parameter must not be null");
         this.parameter = parameter;
         type = getType(context.getSwagger().getDefinitions(), definitionDocumentResolver);
         config = context.getConfig();
-        if (config.isInlineSchemaEnabled()){
-            if(config.isFlatBodyEnabled()) {
-                if (!(type instanceof ObjectType)){
+        if (config.isInlineSchemaEnabled()) {
+            if (config.isFlatBodyEnabled()) {
+                if (!(type instanceof ObjectType)) {
                     type = InlineSchemaUtils.createInlineType(type, parameter.getName(), operation.getId() + " " + parameter.getName(), inlineDefinitions);
                 }
-            }else{
+            } else {
                 type = InlineSchemaUtils.createInlineType(type, parameter.getName(), operation.getId() + " " + parameter.getName(), inlineDefinitions);
             }
         }
     }
 
+    /**
+     * Generate a default example value for parameter.
+     *
+     * @param parameter parameter
+     * @return a generated example for the parameter
+     */
+    public static Object generateExample(AbstractSerializableParameter parameter) {
+        switch (parameter.getType()) {
+            case "integer":
+                return 0;
+            case "number":
+                return 0.0;
+            case "boolean":
+                return true;
+            case "string":
+                return "string";
+            default:
+                return parameter.getType();
+        }
+    }
+
     @JsonIgnore
     public String getAccess() {
         return parameter.getAccess();
@@ -96,8 +117,6 @@ public class ParameterAdapter {
         return boldText(markupDocBuilder, getIn());
     }
 
-
-
     public String getDescription() {
         return parameter.getDescription();
     }
@@ -114,15 +133,15 @@ public class ParameterAdapter {
         return parameter.getVendorExtensions();
     }
 
-    public String getIn(){
+    public String getIn() {
         return WordUtils.capitalize(parameter.getIn());
     }
 
-    public Type getType(){
+    public Type getType() {
         return type;
     }
 
-    public List<ObjectType> getInlineDefinitions(){
+    public List<ObjectType> getInlineDefinitions() {
         return inlineDefinitions;
     }
 
@@ -132,39 +151,37 @@ public class ParameterAdapter {
      * @param definitionDocumentResolver the definition document resolver
      * @return the type of the parameter, or otherwise null
      */
-    private Type getType(Map<String, Model> definitions, DocumentResolver definitionDocumentResolver){
+    private Type getType(Map<String, Model> definitions, DocumentResolver definitionDocumentResolver) {
         Validate.notNull(parameter, "parameter must not be null!");
         Type type = null;
 
-        if(parameter instanceof BodyParameter){
-            BodyParameter bodyParameter = (BodyParameter)parameter;
+        if (parameter instanceof BodyParameter) {
+            BodyParameter bodyParameter = (BodyParameter) parameter;
             Model model = bodyParameter.getSchema();
 
-            if(model != null){
+            if (model != null) {
                 type = ModelUtils.getType(model, definitions, definitionDocumentResolver);
-            }else{
+            } else {
                 type = new BasicType("string", bodyParameter.getName());
             }
 
-        }
-        else if(parameter instanceof AbstractSerializableParameter){
-            AbstractSerializableParameter serializableParameter = (AbstractSerializableParameter)parameter;
+        } else if (parameter instanceof AbstractSerializableParameter) {
+            AbstractSerializableParameter serializableParameter = (AbstractSerializableParameter) parameter;
             @SuppressWarnings("unchecked")
             List<String> enums = serializableParameter.getEnum();
 
-            if(CollectionUtils.isNotEmpty(enums)){
+            if (CollectionUtils.isNotEmpty(enums)) {
                 type = new EnumType(serializableParameter.getName(), enums);
-            }else{
+            } else {
                 type = new BasicType(serializableParameter.getType(), serializableParameter.getName(), serializableParameter.getFormat());
             }
-            if(serializableParameter.getType().equals("array")){
+            if (serializableParameter.getType().equals("array")) {
                 String collectionFormat = serializableParameter.getCollectionFormat();
 
                 type = new ArrayType(serializableParameter.getName(), new PropertyAdapter(serializableParameter.getItems()).getType(definitionDocumentResolver), collectionFormat);
             }
-        }
-        else if(parameter instanceof RefParameter){
-            String refName = ((RefParameter)parameter).getSimpleRef();
+        } else if (parameter instanceof RefParameter) {
+            String refName = ((RefParameter) parameter).getSimpleRef();
 
             type = new RefType(definitionDocumentResolver.apply(refName), new ObjectType(refName, null /* FIXME, not used for now */));
         }
@@ -176,34 +193,13 @@ public class ParameterAdapter {
      *
      * @return the default value of the parameter
      */
-    public Optional<String> getDefaultValue(){
+    public Optional<Object> getDefaultValue() {
         Validate.notNull(parameter, "parameter must not be null!");
-        if(parameter instanceof AbstractSerializableParameter){
-            AbstractSerializableParameter serializableParameter = (AbstractSerializableParameter)parameter;
+        if (parameter instanceof AbstractSerializableParameter) {
+            AbstractSerializableParameter serializableParameter = (AbstractSerializableParameter) parameter;
             return Optional.ofNullable(serializableParameter.getDefaultValue());
         }
         return Optional.empty();
     }
 
-    /**
-     * Generate a default example value for parameter.
-     *
-     * @param parameter parameter
-     * @return a generated example for the parameter
-     */
-    public static Object generateExample(AbstractSerializableParameter parameter) {
-        switch (parameter.getType()) {
-            case "integer":
-                return 0;
-            case "number":
-                return 0.0;
-            case "boolean":
-                return true;
-            case "string":
-                return "string";
-            default:
-                return parameter.getType();
-        }
-    }
-
 }

src/main/java/io/github/swagger2markup/internal/adapter/PropertyAdapter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,7 +23,10 @@ import io.swagger.models.refs.RefFormat;
 import org.apache.commons.collections4.CollectionUtils;
 import org.apache.commons.lang3.BooleanUtils;
 import org.apache.commons.lang3.Validate;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
+import java.math.BigDecimal;
 import java.util.*;
 
 import static org.apache.commons.lang3.StringUtils.isNotBlank;
@@ -31,12 +34,92 @@ import static org.apache.commons.lang3.StringUtils.isNotBlank;
 public final class PropertyAdapter {
 
     private final Property property;
+    private static Logger logger = LoggerFactory.getLogger(PropertyAdapter.class);
 
-    public PropertyAdapter(Property property){
+    public PropertyAdapter(Property property) {
         Validate.notNull(property, "property must not be null");
         this.property = property;
     }
 
+    /**
+     * Generate a default example value for property.
+     *
+     * @param property         property
+     * @param markupDocBuilder doc builder
+     * @return a generated example for the property
+     */
+    public static Object generateExample(Property property, MarkupDocBuilder markupDocBuilder) {
+
+        switch (property.getType()) {
+            case "integer":
+                return 0;
+            case "number":
+                return 0.0;
+            case "boolean":
+                return true;
+            case "string":
+                return "string";
+            case "ref":
+                if (property instanceof RefProperty) {
+                    if (logger.isDebugEnabled()) logger.debug("generateExample RefProperty for " + property.getName());
+                    return markupDocBuilder.copy(false).crossReference(((RefProperty) property).getSimpleRef()).toString();
+                } else {
+                    if (logger.isDebugEnabled()) logger.debug("generateExample for ref not RefProperty");
+                }
+            case "array":
+                if (property instanceof ArrayProperty) {
+                    return generateArrayExample((ArrayProperty) property, markupDocBuilder);
+                }
+            default:
+                return property.getType();
+        }
+    }
+
+    /**
+     * Generate example for an ArrayProperty
+     *
+     * @param property ArrayProperty to generate example for
+     * @param markupDocBuilder MarkupDocBuilder containing all associated settings
+     * @return String example
+     */
+    private static Object generateArrayExample(ArrayProperty property, MarkupDocBuilder markupDocBuilder) {
+        Property itemProperty = property.getItems();
+        List<Object> exampleArray = new ArrayList<>();
+
+        exampleArray.add(generateExample(itemProperty, markupDocBuilder));
+        return exampleArray;
+    }
+
+    /**
+     * Convert a string {@code value} to specified {@code type}.
+     *
+     * @param value value to convert
+     * @param type  target conversion type
+     * @return converted value as object
+     */
+    public static Object convertExample(String value, String type) {
+        if (value == null) {
+            return null;
+        }
+
+        try {
+            switch (type) {
+                case "integer":
+                    return Integer.valueOf(value);
+                case "number":
+                    return Float.valueOf(value);
+                case "boolean":
+                    return Boolean.valueOf(value);
+                case "string":
+                    return value;
+                default:
+                    return value;
+            }
+        } catch (NumberFormatException e) {
+            throw new RuntimeException(String.format("Value '%s' cannot be converted to '%s'", value, type), e);
+        }
+    }
+
     /**
      * Retrieves the type and format of a property.
      *
@@ -70,7 +153,7 @@ public final class PropertyAdapter {
             List<String> enums = stringProperty.getEnum();
             if (CollectionUtils.isNotEmpty(enums)) {
                 type = new EnumType(stringProperty.getTitle(), enums);
-            } else if(isNotBlank(stringProperty.getFormat())) {
+            } else if (isNotBlank(stringProperty.getFormat())) {
                 type = new BasicType(stringProperty.getType(), stringProperty.getTitle(), stringProperty.getFormat());
             } else {
                 type = new BasicType(stringProperty.getType(), stringProperty.getTitle());
@@ -117,7 +200,6 @@ public final class PropertyAdapter {
         }
         return Optional.empty();
     }
-    
 
     /**
      * Retrieves the minLength of a property
@@ -134,7 +216,6 @@ public final class PropertyAdapter {
         }
         return Optional.empty();
     }
-    
 
     /**
      * Retrieves the maxLength of a property
@@ -151,7 +232,7 @@ public final class PropertyAdapter {
         }
         return Optional.empty();
     }
-    
+
     /**
      * Retrieves the pattern of a property
      *
@@ -167,17 +248,17 @@ public final class PropertyAdapter {
         }
         return Optional.empty();
     }
-    
+
     /**
      * Retrieves the minimum value of a property
      *
      * @return the minimum value of the property
      */
-    public Optional<Number> getMin() {
-        if (property instanceof BaseIntegerProperty){
+    public Optional<BigDecimal> getMin() {
+        if (property instanceof BaseIntegerProperty) {
             BaseIntegerProperty integerProperty = (BaseIntegerProperty) property;
-            return Optional.ofNullable(integerProperty.getMinimum() != null ? integerProperty.getMinimum().longValue() : null);
-        } else if (property instanceof AbstractNumericProperty){
+            return Optional.ofNullable(integerProperty.getMinimum() != null ? integerProperty.getMinimum() : null);
+        } else if (property instanceof AbstractNumericProperty) {
             AbstractNumericProperty numericProperty = (AbstractNumericProperty) property;
             return Optional.ofNullable(numericProperty.getMinimum());
         }
@@ -190,23 +271,23 @@ public final class PropertyAdapter {
      * @return the exclusiveMinimum value of the property
      */
     public boolean getExclusiveMin() {
-        if (property instanceof AbstractNumericProperty){
+        if (property instanceof AbstractNumericProperty) {
             AbstractNumericProperty numericProperty = (AbstractNumericProperty) property;
             return BooleanUtils.isTrue(numericProperty.getExclusiveMinimum());
         }
         return false;
     }
-    
+
     /**
      * Retrieves the minimum value of a property
      *
      * @return the minimum value of the property
      */
-    public Optional<Number> getMax() {
-        if (property instanceof BaseIntegerProperty){
+    public Optional<BigDecimal> getMax() {
+        if (property instanceof BaseIntegerProperty) {
             BaseIntegerProperty integerProperty = (BaseIntegerProperty) property;
-            return Optional.ofNullable(integerProperty.getMaximum() != null ? integerProperty.getMaximum().longValue() : null);
-        } else if (property instanceof AbstractNumericProperty){
+            return Optional.ofNullable(integerProperty.getMaximum() != null ? integerProperty.getMaximum() : null);
+        } else if (property instanceof AbstractNumericProperty) {
             AbstractNumericProperty numericProperty = (AbstractNumericProperty) property;
             return Optional.ofNullable(numericProperty.getMaximum());
         }
@@ -219,18 +300,18 @@ public final class PropertyAdapter {
      * @return the exclusiveMaximum value of the property
      */
     public boolean getExclusiveMax() {
-        if (property instanceof AbstractNumericProperty){
+        if (property instanceof AbstractNumericProperty) {
             AbstractNumericProperty numericProperty = (AbstractNumericProperty) property;
             return BooleanUtils.isTrue((numericProperty.getExclusiveMaximum()));
         }
         return false;
     }
-    
+
     /**
      * Return example display string for the given {@code property}.
      *
      * @param generateMissingExamples specifies if missing examples should be generated
-     * @param markupDocBuilder doc builder
+     * @param markupDocBuilder        doc builder
      * @return property example display string
      */
     public Optional<Object> getExample(boolean generateMissingExamples, MarkupDocBuilder markupDocBuilder) {
@@ -259,62 +340,6 @@ public final class PropertyAdapter {
         return Optional.empty();
     }
 
-    /**
-     * Generate a default example value for property.
-     *
-     * @param property         property
-     * @param markupDocBuilder doc builder
-     * @return a generated example for the property
-     */
-    public static Object generateExample(Property property, MarkupDocBuilder markupDocBuilder) {
-        switch (property.getType()) {
-            case "integer":
-                return 0;
-            case "number":
-                return 0.0;
-            case "boolean":
-                return true;
-            case "string":
-                return "string";
-            case "ref":
-                if (property instanceof RefProperty) {
-                    return markupDocBuilder.copy(false).crossReference(((RefProperty) property).getSimpleRef()).toString();
-                }
-            default:
-                return property.getType();
-        }
-    }
-
-    /**
-     * Convert a string {@code value} to specified {@code type}.
-     *
-     * @param value value to convert
-     * @param type  target conversion type
-     * @return converted value as object
-     */
-    public static Object convertExample(String value, String type) {
-        if (value == null) {
-            return null;
-        }
-
-        try {
-            switch (type) {
-                case "integer":
-                    return Integer.valueOf(value);
-                case "number":
-                    return Float.valueOf(value);
-                case "boolean":
-                    return Boolean.valueOf(value);
-                case "string":
-                    return value;
-                default:
-                    return value;
-            }
-        } catch (NumberFormatException e) {
-            throw new RuntimeException(String.format("Value '%s' cannot be converted to '%s'", value, type), e);
-        }
-    }
-
     /**
      * Checks if a property is read-only.
      *

src/main/java/io/github/swagger2markup/internal/component/BodyParameterComponent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -45,28 +45,17 @@ public class BodyParameterComponent extends MarkupComponent<BodyParameterCompone
     private final PropertiesTableComponent propertiesTableComponent;
 
     public BodyParameterComponent(Swagger2MarkupConverter.Context context,
-                                  DocumentResolver definitionDocumentResolver){
+                                  DocumentResolver definitionDocumentResolver) {
         super(context);
         this.definitionDocumentResolver = Validate.notNull(definitionDocumentResolver, "DocumentResolver must not be null");
         this.propertiesTableComponent = new PropertiesTableComponent(context, definitionDocumentResolver);
     }
 
     public static BodyParameterComponent.Parameters parameters(PathOperation operation,
-                                                               List<ObjectType> inlineDefinitions){
+                                                               List<ObjectType> inlineDefinitions) {
         return new BodyParameterComponent.Parameters(operation, inlineDefinitions);
     }
 
-    public static class Parameters{
-        private PathOperation operation;
-        private final List<ObjectType> inlineDefinitions;
-        public Parameters(PathOperation operation,
-                          List<ObjectType> inlineDefinitions){
-            Validate.notNull(operation, "Operation must not be null");
-            this.operation = operation;
-            this.inlineDefinitions = inlineDefinitions;
-        }
-    }
-
     @Override
     public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params) {
         PathOperation operation = params.operation;
@@ -123,4 +112,16 @@ public class BodyParameterComponent extends MarkupComponent<BodyParameterCompone
             markupDocBuilder.sectionTitleLevel4(title);
         }
     }
+
+    public static class Parameters {
+        private final List<ObjectType> inlineDefinitions;
+        private PathOperation operation;
+
+        public Parameters(PathOperation operation,
+                          List<ObjectType> inlineDefinitions) {
+            Validate.notNull(operation, "Operation must not be null");
+            this.operation = operation;
+            this.inlineDefinitions = inlineDefinitions;
+        }
+    }
 }

src/main/java/io/github/swagger2markup/internal/component/ConsumesComponent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -29,22 +29,12 @@ import static io.github.swagger2markup.internal.utils.MarkupDocBuilderUtils.lite
 
 public class ConsumesComponent extends MarkupComponent<ConsumesComponent.Parameters> {
 
-    public ConsumesComponent(Swagger2MarkupConverter.Context context){
+    public ConsumesComponent(Swagger2MarkupConverter.Context context) {
         super(context);
     }
 
-    public static class Parameters {
-        private final List<String> consumes;
-        private final int titleLevel;
-        public Parameters(List<String> consumes,
-                       int titleLevel){
-            this.consumes = Validate.notNull(consumes, "Consumes must not be null");
-            this.titleLevel = titleLevel;
-        }
-    }
-
     public static ConsumesComponent.Parameters parameters(List<String> consumes,
-                                                          int titleLevel){
+                                                          int titleLevel) {
         return new ConsumesComponent.Parameters(consumes, titleLevel);
     }
 
@@ -55,4 +45,15 @@ public class ConsumesComponent extends MarkupComponent<ConsumesComponent.Paramet
                 .map(value -> literalText(markupDocBuilder, value)).collect(Collectors.toList()));
         return markupDocBuilder;
     }
+
+    public static class Parameters {
+        private final List<String> consumes;
+        private final int titleLevel;
+
+        public Parameters(List<String> consumes,
+                          int titleLevel) {
+            this.consumes = Validate.notNull(consumes, "Consumes must not be null");
+            this.titleLevel = titleLevel;
+        }
+    }
 }

src/main/java/io/github/swagger2markup/internal/component/ContactInfoComponent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,8 +16,8 @@
 package io.github.swagger2markup.internal.component;
 
 
-import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.Labels;
+import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
 import io.github.swagger2markup.spi.MarkupComponent;
 import io.swagger.models.Contact;
@@ -32,25 +32,15 @@ public class ContactInfoComponent extends MarkupComponent<ContactInfoComponent.P
         super(context);
     }
 
-    public static class Parameters {
-        private final Contact contact;
-        private final int titleLevel;
-        public Parameters(Contact contact,
-                int titleLevel){
-            this.contact = Validate.notNull(contact, "Contact must not be null");
-            this.titleLevel = titleLevel;
-        }
-    }
-
     public static ContactInfoComponent.Parameters parameters(Contact contact,
-                                                             int titleLevel){
+                                                             int titleLevel) {
         return new ContactInfoComponent.Parameters(contact, titleLevel);
     }
 
     @Override
     public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params) {
         Contact contact = params.contact;
-        if (isNotBlank(contact.getName()) || isNotBlank(contact.getEmail())){
+        if (isNotBlank(contact.getName()) || isNotBlank(contact.getEmail())) {
             markupDocBuilder.sectionTitleLevel(params.titleLevel, labels.getLabel(Labels.CONTACT_INFORMATION));
             MarkupDocBuilder paragraphBuilder = copyMarkupDocBuilder(markupDocBuilder);
             if (isNotBlank(contact.getName())) {
@@ -65,4 +55,15 @@ public class ContactInfoComponent extends MarkupComponent<ContactInfoComponent.P
         }
         return markupDocBuilder;
     }
+
+    public static class Parameters {
+        private final Contact contact;
+        private final int titleLevel;
+
+        public Parameters(Contact contact,
+                          int titleLevel) {
+            this.contact = Validate.notNull(contact, "Contact must not be null");
+            this.titleLevel = titleLevel;
+        }
+    }
 }

src/main/java/io/github/swagger2markup/internal/component/DefinitionComponent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,7 +17,6 @@ package io.github.swagger2markup.internal.component;
 
 
 import io.github.swagger2markup.Swagger2MarkupConverter;
-import io.github.swagger2markup.Labels;
 import io.github.swagger2markup.internal.resolver.DocumentResolver;
 import io.github.swagger2markup.internal.type.ObjectType;
 import io.github.swagger2markup.internal.type.ObjectTypePolymorphism;
@@ -28,7 +27,6 @@ import io.github.swagger2markup.spi.DefinitionsDocumentExtension;
 import io.github.swagger2markup.spi.MarkupComponent;
 import io.swagger.models.Model;
 import org.apache.commons.collections4.CollectionUtils;
-import org.apache.commons.lang3.StringUtils;
 import org.apache.commons.lang3.Validate;
 
 import java.util.*;
@@ -56,32 +54,18 @@ public class DefinitionComponent extends MarkupComponent<DefinitionComponent.Par
         this.definitions = context.getSwagger().getDefinitions();
         this.definitionsDocumentResolver = definitionsDocumentResolver;
         POLYMORPHISM_NATURE = new HashMap<ObjectTypePolymorphism.Nature, String>() {{
-            put(ObjectTypePolymorphism.Nature.COMPOSITION, labels.getLabel(Labels.POLYMORPHISM_NATURE_COMPOSITION));
-            put(ObjectTypePolymorphism.Nature.INHERITANCE, labels.getLabel(Labels.POLYMORPHISM_NATURE_INHERITANCE));
+            put(ObjectTypePolymorphism.Nature.COMPOSITION, labels.getLabel(POLYMORPHISM_NATURE_COMPOSITION));
+            put(ObjectTypePolymorphism.Nature.INHERITANCE, labels.getLabel(POLYMORPHISM_NATURE_INHERITANCE));
         }};
         propertiesTableComponent = new PropertiesTableComponent(context, definitionsDocumentResolver);
     }
 
     public static DefinitionComponent.Parameters parameters(String definitionName,
-                                                             Model model,
-                                                             int titleLevel){
+                                                            Model model,
+                                                            int titleLevel) {
         return new DefinitionComponent.Parameters(definitionName, model, titleLevel);
     }
 
-    public static class Parameters {
-        private final String definitionName;
-        private final Model model;
-        private final int titleLevel;
-
-        public Parameters(String definitionName,
-                Model model,
-                int titleLevel){
-            this.definitionName = Validate.notBlank(definitionName, "DefinitionName must not be empty");
-            this.model = Validate.notNull(model, "Model must not be null");
-            this.titleLevel = titleLevel;
-        }
-    }
-
     @Override
     public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params) {
         String definitionName = params.definitionName;
@@ -117,10 +101,9 @@ public class DefinitionComponent extends MarkupComponent<DefinitionComponent.Par
     /**
      * Builds inline schema definitions
      *
-     * @param markupDocBuilder   the docbuilder do use for output
-     * @param definitions  all inline definitions to display
-     * @param uniquePrefix unique prefix to prepend to inline object names to enforce unicity
-
+     * @param markupDocBuilder the docbuilder do use for output
+     * @param definitions      all inline definitions to display
+     * @param uniquePrefix     unique prefix to prepend to inline object names to enforce unicity
      */
     private void inlineDefinitions(MarkupDocBuilder markupDocBuilder, List<ObjectType> definitions, String uniquePrefix) {
         if (CollectionUtils.isNotEmpty(definitions)) {
@@ -138,20 +121,17 @@ public class DefinitionComponent extends MarkupComponent<DefinitionComponent.Par
     /**
      * Builds the type informations of a definition
      *
-     * @param markupDocBuilder     the docbuilder do use for output
-     * @param definitionName name of the definition to display
-     * @param model          model of the definition to display
-
+     * @param markupDocBuilder the docbuilder do use for output
+     * @param definitionName   name of the definition to display
+     * @param model            model of the definition to display
      * @return a list of inlined types.
      */
     private List<ObjectType> typeSection(MarkupDocBuilder markupDocBuilder, String definitionName, Model model) {
         List<ObjectType> inlineDefinitions = new ArrayList<>();
         Type modelType = ModelUtils.resolveRefType(ModelUtils.getType(model, definitions, definitionsDocumentResolver));
 
-        if (!(modelType instanceof ObjectType)) {
-            if (config.isInlineSchemaEnabled()) {
-                modelType = createInlineType(modelType, definitionName, definitionName + " " + "inline", inlineDefinitions);
-            }
+        if (!(modelType instanceof ObjectType) && config.isInlineSchemaEnabled()) {
+            modelType = createInlineType(modelType, definitionName, definitionName + " " + "inline", inlineDefinitions);
         }
 
         if (modelType instanceof ObjectType) {
@@ -159,23 +139,22 @@ public class DefinitionComponent extends MarkupComponent<DefinitionComponent.Par
             MarkupDocBuilder typeInfos = copyMarkupDocBuilder(markupDocBuilder);
             switch (objectType.getPolymorphism().getNature()) {
                 case COMPOSITION:
-                    typeInfos.italicText(labels.getLabel(Labels.POLYMORPHISM_COLUMN)).textLine(COLON + POLYMORPHISM_NATURE.get(objectType.getPolymorphism().getNature()));
+                    typeInfos.italicText(labels.getLabel(POLYMORPHISM_COLUMN)).textLine(COLON + POLYMORPHISM_NATURE.get(objectType.getPolymorphism().getNature()));
                     break;
                 case INHERITANCE:
                     typeInfos.italicText(labels.getLabel(POLYMORPHISM_COLUMN)).textLine(COLON + POLYMORPHISM_NATURE.get(objectType.getPolymorphism().getNature()));
                     typeInfos.italicText(labels.getLabel(POLYMORPHISM_DISCRIMINATOR_COLUMN)).textLine(COLON + objectType.getPolymorphism().getDiscriminator());
                     break;
                 case NONE:
-                    if (ALWAYS_DISPLAY_DISCRIMINATOR) {
-                        if (StringUtils.isNotBlank(objectType.getPolymorphism().getDiscriminator()))
-                            typeInfos.italicText(labels.getLabel(POLYMORPHISM_DISCRIMINATOR_COLUMN)).textLine(COLON + objectType.getPolymorphism().getDiscriminator());
-                    }
-
-                default: break;
+                    if (ALWAYS_DISPLAY_DISCRIMINATOR && isNotBlank(objectType.getPolymorphism().getDiscriminator()))
+                        typeInfos.italicText(labels.getLabel(POLYMORPHISM_DISCRIMINATOR_COLUMN)).textLine(COLON + objectType.getPolymorphism().getDiscriminator());
+                    break;
+                default:
+                    break;
             }
 
             String typeInfosString = typeInfos.toString();
-            if (StringUtils.isNotBlank(typeInfosString))
+            if (isNotBlank(typeInfosString))
                 markupDocBuilder.paragraph(typeInfosString, true);
 
             propertiesTableComponent.apply(markupDocBuilder,
@@ -193,7 +172,6 @@ public class DefinitionComponent extends MarkupComponent<DefinitionComponent.Par
         return inlineDefinitions;
     }
 
-
     /**
      * Apply extension context to all DefinitionsContentExtension
      *
@@ -203,5 +181,19 @@ public class DefinitionComponent extends MarkupComponent<DefinitionComponent.Par
         extensionRegistry.getDefinitionsDocumentExtensions().forEach(extension -> extension.apply(context));
     }
 
+    public static class Parameters {
+        private final String definitionName;
+        private final Model model;
+        private final int titleLevel;
+
+        public Parameters(String definitionName,
+                          Model model,
+                          int titleLevel) {
+            this.definitionName = Validate.notBlank(definitionName, "DefinitionName must not be empty");
+            this.model = Validate.notNull(model, "Model must not be null");
+            this.titleLevel = titleLevel;
+        }
+    }
+
 
 }

src/main/java/io/github/swagger2markup/internal/component/ExternalDocsComponent.java

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2017 Robert Winkler
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.swagger2markup.internal.component;
+
+import io.github.swagger2markup.Swagger2MarkupConverter;
+import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
+import io.github.swagger2markup.spi.MarkupComponent;
+import io.swagger.models.ExternalDocs;
+import org.apache.commons.lang3.Validate;
+
+import static io.github.swagger2markup.Labels.EXTERNAL_DOCS;
+import static io.github.swagger2markup.Labels.EXTERNAL_DOCS_DESC;
+import static io.github.swagger2markup.Labels.EXTERNAL_DOCS_URL;
+import static io.github.swagger2markup.internal.utils.MarkupDocBuilderUtils.copyMarkupDocBuilder;
+import static org.apache.commons.lang3.StringUtils.isNotBlank;
+
+public class ExternalDocsComponent extends MarkupComponent<ExternalDocsComponent.Parameters> {
+
+    public ExternalDocsComponent(Swagger2MarkupConverter.Context context) {
+        super(context);
+    }
+
+    public static ExternalDocsComponent.Parameters parameters(ExternalDocs externalDocs, int titleLevel) {
+        return new ExternalDocsComponent.Parameters(externalDocs, titleLevel);
+    }
+
+    @Override
+    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params) {
+        ExternalDocs externalDocs = params.externalDocs;
+        String description = externalDocs.getDescription();
+        String url = externalDocs.getUrl();
+        if ((description != null && (isNotBlank(description) || (url != null && isNotBlank(url))))) {
+            markupDocBuilder.sectionTitleLevel(params.titleLevel, labels.getLabel(EXTERNAL_DOCS));
+            MarkupDocBuilder paragraph = copyMarkupDocBuilder(markupDocBuilder);
+
+            if (isNotBlank(description)) {
+                paragraph.italicText(labels.getLabel(EXTERNAL_DOCS_DESC)).textLine(COLON + description);
+            }
+            if (isNotBlank(url)) {
+                paragraph.italicText(labels.getLabel(EXTERNAL_DOCS_URL)).textLine(COLON + url);
+            }
+
+            markupDocBuilder.paragraph(paragraph.toString(), true);
+        }
+
+        return markupDocBuilder;
+    }
+
+    public static class Parameters {
+        private final int titleLevel;
+        private final ExternalDocs externalDocs;
+
+        public Parameters(ExternalDocs externalDocs,
+                          int titleLevel) {
+            this.externalDocs = Validate.notNull(externalDocs, "ExternalDocs must not be null");
+            this.titleLevel = titleLevel;
+        }
+    }
+}

src/main/java/io/github/swagger2markup/internal/component/LicenseInfoComponent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -28,23 +28,12 @@ import static org.apache.commons.lang3.StringUtils.isNotBlank;
 
 public class LicenseInfoComponent extends MarkupComponent<LicenseInfoComponent.Parameters> {
 
-    public LicenseInfoComponent(Swagger2MarkupConverter.Context context){
+    public LicenseInfoComponent(Swagger2MarkupConverter.Context context) {
         super(context);
     }
 
-    public static class Parameters {
-        private final int titleLevel;
-        private final Info info;
-
-        public Parameters(Info info,
-                          int titleLevel){
-            this.info = Validate.notNull(info, "Info must not be null");
-            this.titleLevel = titleLevel;
-        }
-    }
-
     public static LicenseInfoComponent.Parameters parameters(Info info,
-                                                             int titleLevel){
+                                                             int titleLevel) {
         return new LicenseInfoComponent.Parameters(info, titleLevel);
     }
 
@@ -53,7 +42,7 @@ public class LicenseInfoComponent extends MarkupComponent<LicenseInfoComponent.P
         Info info = params.info;
         License license = info.getLicense();
         String termOfService = info.getTermsOfService();
-        if((license != null && (isNotBlank(license.getName()) || isNotBlank(license.getUrl()))) || isNotBlank(termOfService)) {
+        if ((license != null && (isNotBlank(license.getName()) || isNotBlank(license.getUrl()))) || isNotBlank(termOfService)) {
             markupDocBuilder.sectionTitleLevel(params.titleLevel, labels.getLabel(LICENSE_INFORMATION));
             MarkupDocBuilder paragraph = copyMarkupDocBuilder(markupDocBuilder);
             if (license != null) {
@@ -72,4 +61,15 @@ public class LicenseInfoComponent extends MarkupComponent<LicenseInfoComponent.P
 
         return markupDocBuilder;
     }
+
+    public static class Parameters {
+        private final int titleLevel;
+        private final Info info;
+
+        public Parameters(Info info,
+                          int titleLevel) {
+            this.info = Validate.notNull(info, "Info must not be null");
+            this.titleLevel = titleLevel;
+        }
+    }
 }

src/main/java/io/github/swagger2markup/internal/component/ParameterTableComponent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,7 +17,6 @@ package io.github.swagger2markup.internal.component;
 
 
 import ch.netzwerg.paleo.StringColumn;
-import io.github.swagger2markup.Labels;
 import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.internal.adapter.ParameterAdapter;
 import io.github.swagger2markup.internal.resolver.DocumentResolver;
@@ -31,13 +30,12 @@ import org.apache.commons.collections4.CollectionUtils;
 import org.apache.commons.lang3.StringUtils;
 import org.apache.commons.lang3.Validate;
 
-import java.util.Collections;
 import java.util.List;
 import java.util.stream.Collectors;
 
 import static ch.netzwerg.paleo.ColumnIds.StringColumnId;
 import static io.github.swagger2markup.Labels.*;
-import static io.github.swagger2markup.internal.utils.MarkupDocBuilderUtils.*;
+import static io.github.swagger2markup.internal.utils.MarkupDocBuilderUtils.copyMarkupDocBuilder;
 import static org.apache.commons.lang3.StringUtils.isNotBlank;
 
 public class ParameterTableComponent extends MarkupComponent<ParameterTableComponent.Parameters> {
@@ -46,8 +44,8 @@ public class ParameterTableComponent extends MarkupComponent<ParameterTableCompo
     private final DocumentResolver definitionDocumentResolver;
     private final TableComponent tableComponent;
 
-    public ParameterTableComponent(Swagger2MarkupConverter.Context context,
-                                   DocumentResolver definitionDocumentResolver){
+    ParameterTableComponent(Swagger2MarkupConverter.Context context,
+                            DocumentResolver definitionDocumentResolver) {
         super(context);
         this.definitionDocumentResolver = Validate.notNull(definitionDocumentResolver, "DocumentResolver must not be null");
         this.tableComponent = new TableComponent(context);
@@ -56,38 +54,24 @@ public class ParameterTableComponent extends MarkupComponent<ParameterTableCompo
 
     public static ParameterTableComponent.Parameters parameters(PathOperation operation,
                                                                 List<ObjectType> inlineDefinitions,
-                                                                int titleLevel){
+                                                                int titleLevel) {
         return new ParameterTableComponent.Parameters(operation, inlineDefinitions, titleLevel);
     }
 
-    public static class Parameters {
-        private final PathOperation operation;
-        private final int titleLevel;
-        private final List<ObjectType> inlineDefinitions;
-
-        public Parameters(PathOperation operation,
-                          List<ObjectType> inlineDefinitions,
-                          int titleLevel){
-            this.operation = Validate.notNull(operation, "PathOperation must not be null");
-            this.inlineDefinitions = Validate.notNull(inlineDefinitions, "InlineDefinitions must not be null");
-            this.titleLevel = titleLevel;
-        }
-    }
-
     @Override
     public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params) {
         PathOperation operation = params.operation;
         List<ObjectType> inlineDefinitions = params.inlineDefinitions;
         List<Parameter> parameters = operation.getOperation().getParameters();
         if (config.getParameterOrdering() != null)
-            Collections.sort(parameters, config.getParameterOrdering());
+            parameters.sort(config.getParameterOrdering());
 
         // Filter parameters to display in parameters section
         List<Parameter> filteredParameters = parameters.stream()
                 .filter(this::filterParameter).collect(Collectors.toList());
 
         MarkupDocBuilder parametersBuilder = copyMarkupDocBuilder(markupDocBuilder);
-        applyPathsDocumentExtension(new PathsDocumentExtension.Context(PathsDocumentExtension.Position.OPERATION_DESCRIPTION_BEGIN, parametersBuilder, operation));
+        applyPathsDocumentExtension(new PathsDocumentExtension.Context(PathsDocumentExtension.Position.OPERATION_PARAMETERS_BEGIN, parametersBuilder, operation));
         if (CollectionUtils.isNotEmpty(filteredParameters)) {
             StringColumn.Builder typeColumnBuilder = StringColumn.builder(StringColumnId.of(labels.getLabel(TYPE_COLUMN)))
                     .putMetaData(TableComponent.WIDTH_RATIO, "2");
@@ -123,12 +107,12 @@ public class ParameterTableComponent extends MarkupComponent<ParameterTableCompo
                     schemaColumnBuilder.build(),
                     defaultColumnBuilder.build()));
         }
-        applyPathsDocumentExtension(new PathsDocumentExtension.Context(PathsDocumentExtension.Position.OPERATION_DESCRIPTION_END, parametersBuilder, operation));
+        applyPathsDocumentExtension(new PathsDocumentExtension.Context(PathsDocumentExtension.Position.OPERATION_PARAMETERS_END, parametersBuilder, operation));
         String parametersContent = parametersBuilder.toString();
 
         applyPathsDocumentExtension(new PathsDocumentExtension.Context(PathsDocumentExtension.Position.OPERATION_PARAMETERS_BEFORE, markupDocBuilder, operation));
         if (isNotBlank(parametersContent)) {
-            markupDocBuilder.sectionTitleLevel(params.titleLevel, labels.getLabel(Labels.PARAMETERS));
+            markupDocBuilder.sectionTitleLevel(params.titleLevel, labels.getLabel(PARAMETERS));
             markupDocBuilder.text(parametersContent);
         }
         applyPathsDocumentExtension(new PathsDocumentExtension.Context(PathsDocumentExtension.Position.OPERATION_PARAMETERS_AFTER, markupDocBuilder, operation));
@@ -136,7 +120,7 @@ public class ParameterTableComponent extends MarkupComponent<ParameterTableCompo
         return markupDocBuilder;
     }
 
-    private String getParameterNameColumnContent(MarkupDocBuilder markupDocBuilder, ParameterAdapter parameter){
+    private String getParameterNameColumnContent(MarkupDocBuilder markupDocBuilder, ParameterAdapter parameter) {
         MarkupDocBuilder parameterNameContent = copyMarkupDocBuilder(markupDocBuilder);
 
         parameterNameContent.boldTextLine(parameter.getName(), true);
@@ -165,4 +149,18 @@ public class ParameterTableComponent extends MarkupComponent<ParameterTableCompo
     private void applyPathsDocumentExtension(PathsDocumentExtension.Context context) {
         extensionRegistry.getPathsDocumentExtensions().forEach(extension -> extension.apply(context));
     }
+
+    public static class Parameters {
+        private final PathOperation operation;
+        private final int titleLevel;
+        private final List<ObjectType> inlineDefinitions;
+
+        public Parameters(PathOperation operation,
+                          List<ObjectType> inlineDefinitions,
+                          int titleLevel) {
+            this.operation = Validate.notNull(operation, "PathOperation must not be null");
+            this.inlineDefinitions = Validate.notNull(inlineDefinitions, "InlineDefinitions must not be null");
+            this.titleLevel = titleLevel;
+        }
+    }
 }

src/main/java/io/github/swagger2markup/internal/component/PathOperationComponent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,9 +16,12 @@
 package io.github.swagger2markup.internal.component;
 
 
+import com.fasterxml.jackson.core.JsonFactory;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
 import io.github.swagger2markup.GroupBy;
+import io.github.swagger2markup.PageBreakLocations;
 import io.github.swagger2markup.Swagger2MarkupConverter;
-import io.github.swagger2markup.Labels;
 import io.github.swagger2markup.internal.resolver.DocumentResolver;
 import io.github.swagger2markup.internal.type.ObjectType;
 import io.github.swagger2markup.internal.utils.ExamplesUtil;
@@ -32,14 +35,14 @@ import io.swagger.models.Model;
 import io.swagger.util.Json;
 import org.apache.commons.collections4.CollectionUtils;
 import org.apache.commons.lang3.BooleanUtils;
+import org.apache.commons.lang3.StringEscapeUtils;
 import org.apache.commons.lang3.Validate;
+import org.apache.commons.lang3.math.NumberUtils;
 
-import java.util.ArrayList;
-import java.util.Collections;
-import java.util.List;
-import java.util.Map;
+import java.util.*;
 
 import static io.github.swagger2markup.Labels.*;
+import static io.github.swagger2markup.PageBreakLocations.*;
 import static io.github.swagger2markup.internal.utils.MarkupDocBuilderUtils.copyMarkupDocBuilder;
 import static io.github.swagger2markup.internal.utils.MarkupDocBuilderUtils.markupDescription;
 import static io.github.swagger2markup.spi.PathsDocumentExtension.Position;
@@ -59,7 +62,7 @@ public class PathOperationComponent extends MarkupComponent<PathOperationCompone
 
     public PathOperationComponent(Swagger2MarkupConverter.Context context,
                                   DocumentResolver definitionDocumentResolver,
-                                  DocumentResolver securityDocumentResolver){
+                                  DocumentResolver securityDocumentResolver) {
         super(context);
         this.definitions = context.getSwagger().getDefinitions();
         this.definitionDocumentResolver = Validate.notNull(definitionDocumentResolver, "DocumentResolver must not be null");
@@ -72,46 +75,61 @@ public class PathOperationComponent extends MarkupComponent<PathOperationCompone
         this.responseComponent = new ResponseComponent(context, definitionDocumentResolver);
     }
 
-    public static PathOperationComponent.Parameters parameters(PathOperation operation){
+    public static PathOperationComponent.Parameters parameters(PathOperation operation) {
         return new PathOperationComponent.Parameters(operation);
     }
 
-    public static class Parameters {
-
-        private final PathOperation operation;
-
-        public Parameters(PathOperation operation){
-            this.operation = Validate.notNull(operation, "PathOperation must not be null");
-        }
-    }
-
     @Override
     public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params) {
         PathOperation operation = params.operation;
+        List<PageBreakLocations> locations = config.getPageBreakLocations();
+
         applyPathsDocumentExtension(new PathsDocumentExtension.Context(Position.OPERATION_BEFORE, markupDocBuilder, operation));
+
+        if (locations.contains(BEFORE_OPERATION)) markupDocBuilder.pageBreak();
         buildOperationTitle(markupDocBuilder, operation);
+
         applyPathsDocumentExtension(new PathsDocumentExtension.Context(Position.OPERATION_BEGIN, markupDocBuilder, operation));
         buildDeprecatedSection(markupDocBuilder, operation);
+
+        if (locations.contains(BEFORE_OPERATION_DESCRIPTION)) markupDocBuilder.pageBreak();
         buildDescriptionSection(markupDocBuilder, operation);
+        if (locations.contains(AFTER_OPERATION_DESCRIPTION)) markupDocBuilder.pageBreak();
+
+        if (locations.contains(BEFORE_OPERATION_PARAMETERS)) markupDocBuilder.pageBreak();
         inlineDefinitions(markupDocBuilder, buildParametersSection(markupDocBuilder, operation), operation.getPath() + " " + operation.getMethod());
+        if (locations.contains(AFTER_OPERATION_PARAMETERS)) markupDocBuilder.pageBreak();
+
         inlineDefinitions(markupDocBuilder, buildBodyParameterSection(markupDocBuilder, operation), operation.getPath() + " " + operation.getMethod());
+
+        if (locations.contains(BEFORE_OPERATION_RESPONSES)) markupDocBuilder.pageBreak();
         inlineDefinitions(markupDocBuilder, buildResponsesSection(markupDocBuilder, operation), operation.getPath() + " " + operation.getMethod());
+        if (locations.contains(AFTER_OPERATION_RESPONSES)) markupDocBuilder.pageBreak();
+
+        if (locations.contains(BEFORE_OPERATION_CONSUMES)) markupDocBuilder.pageBreak();
         buildConsumesSection(markupDocBuilder, operation);
+        if (locations.contains(AFTER_OPERATION_CONSUMES)) markupDocBuilder.pageBreak();
+
+        if (locations.contains(BEFORE_OPERATION_PRODUCES)) markupDocBuilder.pageBreak();
         buildProducesSection(markupDocBuilder, operation);
+        if (locations.contains(AFTER_OPERATION_PRODUCES)) markupDocBuilder.pageBreak();
+
         buildTagsSection(markupDocBuilder, operation);
         buildSecuritySchemeSection(markupDocBuilder, operation);
-        buildExamplesSection(markupDocBuilder, operation);
+        buildExamplesSection(markupDocBuilder, operation, locations);
         applyPathsDocumentExtension(new PathsDocumentExtension.Context(Position.OPERATION_END, markupDocBuilder, operation));
         applyPathsDocumentExtension(new PathsDocumentExtension.Context(Position.OPERATION_AFTER, markupDocBuilder, operation));
+
+        if (locations.contains(AFTER_OPERATION)) markupDocBuilder.pageBreak();
+
         return markupDocBuilder;
     }
 
-
     /**
      * Adds the operation title to the document. If the operation has a summary, the title is the summary.
      * Otherwise the title is the method of the operation and the URL of the operation.
      *
-     * @param operation  the Swagger Operation
+     * @param operation the Swagger Operation
      */
     private void buildOperationTitle(MarkupDocBuilder markupDocBuilder, PathOperation operation) {
         buildOperationTitle(markupDocBuilder, operation.getTitle(), operation.getId());
@@ -123,8 +141,8 @@ public class PathOperationComponent extends MarkupComponent<PathOperationCompone
     /**
      * Adds a operation title to the document.
      *
-     * @param title      the operation title
-     * @param anchor     optional anchor (null => auto-generate from title)
+     * @param title  the operation title
+     * @param anchor optional anchor (null => auto-generate from title)
      */
     private void buildOperationTitle(MarkupDocBuilder markupDocBuilder, String title, String anchor) {
         if (config.getPathsGroupedBy() == GroupBy.AS_IS) {
@@ -137,7 +155,7 @@ public class PathOperationComponent extends MarkupComponent<PathOperationCompone
     /**
      * Builds a warning if method is deprecated.
      *
-     * @param operation  the Swagger Operation
+     * @param operation the Swagger Operation
      */
     private void buildDeprecatedSection(MarkupDocBuilder markupDocBuilder, PathOperation operation) {
         if (BooleanUtils.isTrue(operation.getOperation().isDeprecated())) {
@@ -148,7 +166,7 @@ public class PathOperationComponent extends MarkupComponent<PathOperationCompone
     /**
      * Adds a operation description to the document.
      *
-     * @param operation  the Swagger Operation
+     * @param operation the Swagger Operation
      */
     private void buildDescriptionSection(MarkupDocBuilder markupDocBuilder, PathOperation operation) {
         MarkupDocBuilder descriptionBuilder = copyMarkupDocBuilder(markupDocBuilder);
@@ -162,7 +180,7 @@ public class PathOperationComponent extends MarkupComponent<PathOperationCompone
 
         applyPathsDocumentExtension(new PathsDocumentExtension.Context(Position.OPERATION_DESCRIPTION_BEFORE, markupDocBuilder, operation));
         if (isNotBlank(descriptionContent)) {
-            buildSectionTitle(markupDocBuilder, labels.getLabel(Labels.DESCRIPTION));
+            buildSectionTitle(markupDocBuilder, labels.getLabel(DESCRIPTION));
             markupDocBuilder.text(descriptionContent);
         }
         applyPathsDocumentExtension(new PathsDocumentExtension.Context(Position.OPERATION_DESCRIPTION_AFTER, markupDocBuilder, operation));
@@ -171,7 +189,7 @@ public class PathOperationComponent extends MarkupComponent<PathOperationCompone
     /**
      * Builds the parameters section
      *
-     * @param operation  the Swagger Operation
+     * @param operation the Swagger Operation
      */
     private List<ObjectType> buildParametersSection(MarkupDocBuilder markupDocBuilder, PathOperation operation) {
 
@@ -189,7 +207,7 @@ public class PathOperationComponent extends MarkupComponent<PathOperationCompone
     /**
      * Builds the body parameter section
      *
-     * @param operation  the Swagger Operation
+     * @param operation the Swagger Operation
      * @return a list of inlined types.
      */
     private List<ObjectType> buildBodyParameterSection(MarkupDocBuilder markupDocBuilder, PathOperation operation) {
@@ -218,7 +236,7 @@ public class PathOperationComponent extends MarkupComponent<PathOperationCompone
     /**
      * Adds a operation section title to the document.
      *
-     * @param title      the section title
+     * @param title the section title
      */
     private void buildSectionTitle(MarkupDocBuilder markupDocBuilder, String title) {
         if (config.getPathsGroupedBy() == GroupBy.AS_IS) {
@@ -228,14 +246,12 @@ public class PathOperationComponent extends MarkupComponent<PathOperationCompone
         }
     }
 
-
-
     /**
      * Builds the title of an inline schema.
      * Inline definitions should never been referenced in TOC because they have no real existence, so they are just text.
      *
-     * @param title      inline schema title
-     * @param anchor     inline schema anchor
+     * @param title  inline schema title
+     * @param anchor inline schema anchor
      */
     private void addInlineDefinitionTitle(MarkupDocBuilder markupDocBuilder, String title, String anchor) {
         markupDocBuilder.anchor(anchor);
@@ -245,10 +261,10 @@ public class PathOperationComponent extends MarkupComponent<PathOperationCompone
 
     /**
      * Builds inline schema definitions
-
-     * @param markupDocBuilder   the docbuilder do use for output
-     * @param definitions  all inline definitions to display
-     * @param uniquePrefix unique prefix to prepend to inline object names to enforce unicity
+     *
+     * @param markupDocBuilder the docbuilder do use for output
+     * @param definitions      all inline definitions to display
+     * @param uniquePrefix     unique prefix to prepend to inline object names to enforce unicity
      */
     private void inlineDefinitions(MarkupDocBuilder markupDocBuilder, List<ObjectType> definitions, String uniquePrefix) {
         if (CollectionUtils.isNotEmpty(definitions)) {
@@ -256,11 +272,11 @@ public class PathOperationComponent extends MarkupComponent<PathOperationCompone
                 addInlineDefinitionTitle(markupDocBuilder, definition.getName(), definition.getUniqueName());
 
                 List<ObjectType> localDefinitions = new ArrayList<>();
-                        propertiesTableComponent.apply(markupDocBuilder, PropertiesTableComponent.parameters(
-                                definition.getProperties(),
-                                uniquePrefix,
-                                localDefinitions
-                        ));
+                propertiesTableComponent.apply(markupDocBuilder, PropertiesTableComponent.parameters(
+                        definition.getProperties(),
+                        uniquePrefix,
+                        localDefinitions
+                ));
                 for (ObjectType localDefinition : localDefinitions)
                     inlineDefinitions(markupDocBuilder, Collections.singletonList(localDefinition), localDefinition.getUniqueName());
             }
@@ -291,7 +307,7 @@ public class PathOperationComponent extends MarkupComponent<PathOperationCompone
             if (CollectionUtils.isNotEmpty(tags)) {
                 buildSectionTitle(markupDocBuilder, labels.getLabel(TAGS));
                 if (config.getTagOrdering() != null) {
-                    Collections.sort(tags, config.getTagOrdering());
+                    tags.sort(config.getTagOrdering());
                 }
                 markupDocBuilder.unorderedList(tags);
             }
@@ -301,7 +317,7 @@ public class PathOperationComponent extends MarkupComponent<PathOperationCompone
     /**
      * Builds the security section of a Swagger Operation.
      *
-     * @param operation  the Swagger Operation
+     * @param operation the Swagger Operation
      */
     private void buildSecuritySchemeSection(MarkupDocBuilder markupDocBuilder, PathOperation operation) {
         if (config.isPathSecuritySectionEnabled()) {
@@ -323,35 +339,120 @@ public class PathOperationComponent extends MarkupComponent<PathOperationCompone
         }
     }
 
-
     /**
      * Builds the example section of a Swagger Operation.
      *
-     * @param operation  the Swagger Operation
+     * @param operation the Swagger Operation
      */
-    private void buildExamplesSection(MarkupDocBuilder markupDocBuilder, PathOperation operation) {
-
+    private void buildExamplesSection(MarkupDocBuilder markupDocBuilder, PathOperation operation, List<PageBreakLocations> locations) {
+        // Generate examples
         Map<String, Object> generatedRequestExampleMap = ExamplesUtil.generateRequestExampleMap(config.isGeneratedExamplesEnabled(), operation, definitions, definitionDocumentResolver, markupDocBuilder);
         Map<String, Object> generatedResponseExampleMap = ExamplesUtil.generateResponseExampleMap(config.isGeneratedExamplesEnabled(), operation, definitions, definitionDocumentResolver, markupDocBuilder);
 
-        exampleMap(markupDocBuilder, generatedRequestExampleMap, labels.getLabel(EXAMPLE_REQUEST), labels.getLabel(REQUEST));
-        exampleMap(markupDocBuilder, generatedResponseExampleMap, labels.getLabel(EXAMPLE_RESPONSE), labels.getLabel(RESPONSE));
+        // Get page break settings
+        boolean beforeExampleRequestBreak = locations.contains(BEFORE_OPERATION_EXAMPLE_REQUEST);
+        boolean afterExampleRequestBreak = locations.contains(AFTER_OPERATION_EXAMPLE_REQUEST);
+        boolean beforeExampleResponseBreak = locations.contains(BEFORE_OPERATION_EXAMPLE_RESPONSE);
+        boolean afterExampleResponseBreak = locations.contains(AFTER_OPERATION_EXAMPLE_RESPONSE);
+
+        // Write examples
+        exampleMap(markupDocBuilder, generatedRequestExampleMap, labels.getLabel(EXAMPLE_REQUEST), labels.getLabel(REQUEST), beforeExampleRequestBreak, afterExampleRequestBreak);
+        exampleMap(markupDocBuilder, generatedResponseExampleMap, labels.getLabel(EXAMPLE_RESPONSE), labels.getLabel(RESPONSE), beforeExampleResponseBreak, afterExampleResponseBreak);
     }
 
-    private void exampleMap(MarkupDocBuilder markupDocBuilder, Map<String, Object> exampleMap, String operationSectionTitle, String sectionTitle) {
+    private void exampleMap(MarkupDocBuilder markupDocBuilder, Map<String, Object> exampleMap, String operationSectionTitle, String sectionTitle, boolean beforeBreak, boolean afterBreak) {
         if (exampleMap.size() > 0) {
+            if (beforeBreak) markupDocBuilder.pageBreak();
             buildSectionTitle(markupDocBuilder, operationSectionTitle);
             for (Map.Entry<String, Object> entry : exampleMap.entrySet()) {
+
+                // Example title, like "Response 200" or "Request Body"
                 buildExampleTitle(markupDocBuilder, sectionTitle + " " + entry.getKey());
-                markupDocBuilder.listingBlock(Json.pretty(entry.getValue()), "json");
+
+                if (NumberUtils.isNumber(entry.getKey())) {
+                    // Section header is an HTTP status code (numeric)
+                    JsonNode rootNode = parseExample(entry.getValue());
+                    Iterator<Map.Entry<String, JsonNode>> fieldsIterator = rootNode.fields();
+
+
+                    if (!fieldsIterator.hasNext()) {
+                        // rootNode contains a single example, no need to further iterate.
+                        String example = Json.pretty(rootNode);
+//                        String example = Json.pretty(stripExampleQuotes(rootNode.toString()));
+//                        example = Json.pretty(example);
+                        markupDocBuilder.listingBlock(example, "json");
+                    }
+                    while (fieldsIterator.hasNext()) {
+                        Map.Entry<String, JsonNode> field = fieldsIterator.next();
+
+                        if (field.getKey().equals("application/json")) {
+                            String example = Json.pretty(field.getValue());
+                            example = stripExampleQuotes(StringEscapeUtils.unescapeJson(example));
+
+                            markupDocBuilder.listingBlock(example, "json");
+
+                        } else if (field.getKey().equals("application/xml")) {
+
+                            String example = stripExampleQuotes(field.getValue().toString());
+                            example = StringEscapeUtils.unescapeJava(example);
+
+                            //TODO: pretty print XML
+
+                            markupDocBuilder.listingBlock(example, "xml");
+                        } else {
+                            String example = Json.pretty(entry.getValue());
+                            markupDocBuilder.listingBlock(example, "json");
+                            break; // No need to print the same example multiple times
+                        }
+                    }
+                } else if (entry.getKey().equals("path")) {
+                    // Path shouldn't have quotes around it
+                    markupDocBuilder.listingBlock(entry.getValue().toString());
+                } else if (entry.getKey().equals("query")) {
+                    //TODO issue #264: print query parameters in table
+                    // markupDocBuilder.listingBlock(entry.getValue().toString());
+                    logger.debug("Skipping query parameter: " + entry.getValue().toString());
+                } else {
+                    markupDocBuilder.listingBlock(Json.pretty(entry.getValue()), "json");
+                }
             }
+            if (afterBreak) markupDocBuilder.pageBreak();
+        }
+    }
+
+    /**
+     * Strip leading and trailing quotes from a string
+     *
+     * @param raw String containing leading or trailing quotes
+     * @return parsed String
+     */
+    private String stripExampleQuotes(String raw) {
+        return raw
+                .replaceAll("^\"+", "")  // Strip leading quotes
+                .replaceAll("\"+$", ""); // Strip trailing quotes
+    }
+
+    /**
+     * Parse a JSON array
+     *
+     * @param raw Object containing a JSON string
+     * @return JsonNode[contentType, example]
+     * @throws RuntimeException when the given JSON string cannot be parsed
+     */
+    private JsonNode parseExample(Object raw) throws RuntimeException {
+        try {
+            JsonFactory factory = new JsonFactory();
+            ObjectMapper mapper = new ObjectMapper(factory);
+            return mapper.readTree(Json.pretty(raw));
+        } catch (Exception ex) {
+            throw new RuntimeException("Failed to read example", ex);
         }
     }
 
     /**
      * Adds a example title to the document.
      *
-     * @param title      the section title
+     * @param title the section title
      */
     private void buildExampleTitle(MarkupDocBuilder markupDocBuilder, String title) {
         if (config.getPathsGroupedBy() == GroupBy.AS_IS) {
@@ -361,7 +462,6 @@ public class PathOperationComponent extends MarkupComponent<PathOperationCompone
         }
     }
 
-
     /**
      * Apply extension context to all OperationsContentExtension.
      *
@@ -370,4 +470,13 @@ public class PathOperationComponent extends MarkupComponent<PathOperationCompone
     private void applyPathsDocumentExtension(PathsDocumentExtension.Context context) {
         extensionRegistry.getPathsDocumentExtensions().forEach(extension -> extension.apply(context));
     }
+
+    public static class Parameters {
+
+        private final PathOperation operation;
+
+        public Parameters(PathOperation operation) {
+            this.operation = Validate.notNull(operation, "PathOperation must not be null");
+        }
+    }
 }

src/main/java/io/github/swagger2markup/internal/component/ProducesComponent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,8 +16,8 @@
 package io.github.swagger2markup.internal.component;
 
 
-import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.Labels;
+import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
 import io.github.swagger2markup.spi.MarkupComponent;
 import org.apache.commons.lang3.Validate;
@@ -30,30 +30,30 @@ import static io.github.swagger2markup.internal.utils.MarkupDocBuilderUtils.lite
 public class ProducesComponent extends MarkupComponent<ProducesComponent.Parameters> {
 
 
-    public ProducesComponent(Swagger2MarkupConverter.Context context){
+    public ProducesComponent(Swagger2MarkupConverter.Context context) {
         super(context);
     }
 
+    public static ProducesComponent.Parameters parameters(List<String> consumes,
+                                                          int titleLevel) {
+        return new ProducesComponent.Parameters(consumes, titleLevel);
+    }
+
+    @Override
+    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params) {
+        markupDocBuilder.sectionTitleLevel(params.titleLevel, labels.getLabel(Labels.PRODUCES));
+        markupDocBuilder.unorderedList(params.produces.stream()
+                .map(value -> literalText(markupDocBuilder, value)).collect(Collectors.toList()));
+        return markupDocBuilder;
+    }
+
     public static class Parameters {
         private final List<String> produces;
         private final int titleLevel;
 
-        public Parameters(List<String> produces, int titleLevel){
+        public Parameters(List<String> produces, int titleLevel) {
             this.produces = Validate.notNull(produces, "Produces must not be null");
             this.titleLevel = titleLevel;
         }
     }
-
-    public static ProducesComponent.Parameters parameters(List<String> consumes,
-                                                          int titleLevel){
-        return new ProducesComponent.Parameters(consumes, titleLevel);
-    }
-
-    @Override
-    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params){
-        markupDocBuilder.sectionTitleLevel(params.titleLevel, labels.getLabel(Labels.PRODUCES));
-        markupDocBuilder.unorderedList(params.produces.stream()
-                .map(value -> literalText(markupDocBuilder, value)).collect(Collectors.toList()));
-        return markupDocBuilder;
-    }
 }

src/main/java/io/github/swagger2markup/internal/component/PropertiesTableComponent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,10 +18,11 @@ package io.github.swagger2markup.internal.component;
 import ch.netzwerg.paleo.ColumnIds;
 import ch.netzwerg.paleo.StringColumn;
 import io.github.swagger2markup.Swagger2MarkupConverter;
+import io.github.swagger2markup.internal.adapter.PropertyAdapter;
 import io.github.swagger2markup.internal.resolver.DocumentResolver;
 import io.github.swagger2markup.internal.type.ObjectType;
+import io.github.swagger2markup.internal.type.RefType;
 import io.github.swagger2markup.internal.type.Type;
-import io.github.swagger2markup.internal.adapter.PropertyAdapter;
 import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
 import io.github.swagger2markup.spi.MarkupComponent;
 import io.swagger.models.properties.Property;
@@ -29,6 +30,9 @@ import io.swagger.util.Json;
 import org.apache.commons.collections4.MapUtils;
 import org.apache.commons.lang3.Validate;
 
+import java.math.BigDecimal;
+import java.text.DecimalFormat;
+import java.text.DecimalFormatSymbols;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
@@ -52,44 +56,32 @@ public class PropertiesTableComponent extends MarkupComponent<PropertiesTableCom
      *
      * @param definitionDocumentResolver definition document resolver to apply to property type cross-reference
      */
-    public PropertiesTableComponent(Swagger2MarkupConverter.Context context,
-                                    DocumentResolver definitionDocumentResolver){
+    PropertiesTableComponent(Swagger2MarkupConverter.Context context,
+      DocumentResolver definitionDocumentResolver) {
         super(context);
         this.definitionDocumentResolver = definitionDocumentResolver;
         this.tableComponent = new TableComponent(context);
     }
 
     public static PropertiesTableComponent.Parameters parameters(Map<String, Property> properties,
-                                                                 String parameterName,
-                                                                 List<ObjectType> inlineDefinitions){
+      String parameterName,
+      List<ObjectType> inlineDefinitions) {
         return new PropertiesTableComponent.Parameters(properties, parameterName, inlineDefinitions);
     }
 
-
-    public static class Parameters {
-        private final Map<String, Property> properties;
-        private final String parameterName;
-        private final List<ObjectType> inlineDefinitions;
-
-        public Parameters(Map<String, Property> properties,
-                          String parameterName,
-                          List<ObjectType> inlineDefinitions){
-
-            this.properties = Validate.notNull(properties, "Properties must not be null");
-            this.parameterName = Validate.notBlank(parameterName, "ParameterName must not be blank");
-            this.inlineDefinitions = Validate.notNull(inlineDefinitions, "InlineDefinitions must not be null");
-        }
-    }
-
-    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params){
+    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params) {
+        //TODO: This method is too complex, split it up in smaller methods to increase readability
         StringColumn.Builder nameColumnBuilder = StringColumn.builder(ColumnIds.StringColumnId.of(labels.getLabel(NAME_COLUMN)))
-                .putMetaData(TableComponent.WIDTH_RATIO, "3");
+          .putMetaData(TableComponent.WIDTH_RATIO, "3");
+
         StringColumn.Builder descriptionColumnBuilder = StringColumn.builder(ColumnIds.StringColumnId.of(labels.getLabel(DESCRIPTION_COLUMN)))
-                .putMetaData(TableComponent.WIDTH_RATIO, "11")
-                .putMetaData(TableComponent.HEADER_COLUMN, "true");
+          .putMetaData(TableComponent.WIDTH_RATIO, "11")
+          .putMetaData(TableComponent.HEADER_COLUMN, "true");
+
         StringColumn.Builder schemaColumnBuilder = StringColumn.builder(ColumnIds.StringColumnId.of(labels.getLabel(SCHEMA_COLUMN)))
-                .putMetaData(TableComponent.WIDTH_RATIO, "4")
-                .putMetaData(TableComponent.HEADER_COLUMN, "true");
+          .putMetaData(TableComponent.WIDTH_RATIO, "4")
+          .putMetaData(TableComponent.HEADER_COLUMN, "true");
+
         Map<String, Property> properties = params.properties;
         if (MapUtils.isNotEmpty(properties)) {
             Map<String, Property> sortedProperties = toSortedMap(properties, config.getPropertyOrdering());
@@ -106,9 +98,10 @@ public class PropertiesTableComponent extends MarkupComponent<PropertiesTableCom
                 Optional<Integer> optionalMaxLength = propertyAdapter.getMaxlength();
                 Optional<Integer> optionalMinLength = propertyAdapter.getMinlength();
                 Optional<String> optionalPattern = propertyAdapter.getPattern();
-                Optional<Number> optionalMinValue = propertyAdapter.getMin();
+
+                Optional<BigDecimal> optionalMinValue = propertyAdapter.getMin();
                 boolean exclusiveMin = propertyAdapter.getExclusiveMin();
-                Optional<Number> optionalMaxValue = propertyAdapter.getMax();
+                Optional<BigDecimal> optionalMaxValue = propertyAdapter.getMax();
                 boolean exclusiveMax = propertyAdapter.getExclusiveMax();
 
                 MarkupDocBuilder propertyNameContent = copyMarkupDocBuilder(markupDocBuilder);
@@ -173,12 +166,15 @@ public class PropertiesTableComponent extends MarkupComponent<PropertiesTableCom
                     descriptionContent.boldText(labels.getLabel(PATTERN_COLUMN)).text(COLON).literalText(Json.pretty(optionalPattern.get()));
                 }
 
+                DecimalFormat numberFormatter = new DecimalFormat("#.##",
+                  DecimalFormatSymbols.getInstance(config.getOutputLanguage().toLocale()));
+
                 if (optionalMinValue.isPresent()) {
                     if (isNotBlank(descriptionContent.toString())) {
                         descriptionContent.newLine(true);
                     }
                     String minValueColumn = exclusiveMin ? labels.getLabel(MINVALUE_EXCLUSIVE_COLUMN) : labels.getLabel(MINVALUE_COLUMN);
-                    descriptionContent.boldText(minValueColumn).text(COLON).literalText(optionalMinValue.get().toString());
+                    descriptionContent.boldText(minValueColumn).text(COLON).literalText(numberFormatter.format(optionalMinValue.get()));
                 }
 
                 if (optionalMaxValue.isPresent()) {
@@ -186,14 +182,19 @@ public class PropertiesTableComponent extends MarkupComponent<PropertiesTableCom
                         descriptionContent.newLine(true);
                     }
                     String maxValueColumn = exclusiveMax ? labels.getLabel(MAXVALUE_EXCLUSIVE_COLUMN) : labels.getLabel(MAXVALUE_COLUMN);
-                    descriptionContent.boldText(maxValueColumn).text(COLON).literalText(optionalMaxValue.get().toString());
+                    descriptionContent.boldText(maxValueColumn).text(COLON).literalText(numberFormatter.format(optionalMaxValue.get()));
                 }
 
                 if (optionalExample.isPresent()) {
                     if (isNotBlank(description) || optionalDefaultValue.isPresent()) {
                         descriptionContent.newLine(true);
                     }
-                    descriptionContent.boldText(labels.getLabel(EXAMPLE_COLUMN)).text(COLON).literalText(Json.pretty(optionalExample.get()));
+
+                    if(propertyType instanceof RefType && isReferenceLink(optionalExample.get().toString())) {
+                        descriptionContent.boldText(labels.getLabel(EXAMPLE_COLUMN)).text(COLON).crossReference(optionalExample.get().toString());
+                    } else {
+                        descriptionContent.boldText(labels.getLabel(EXAMPLE_COLUMN)).text(COLON).literalText(Json.pretty(optionalExample.get()));
+                    }
                 }
 
                 nameColumnBuilder.add(propertyNameContent.toString());
@@ -203,8 +204,33 @@ public class PropertiesTableComponent extends MarkupComponent<PropertiesTableCom
         }
 
         return tableComponent.apply(markupDocBuilder, TableComponent.parameters(
-                nameColumnBuilder.build(),
-                descriptionColumnBuilder.build(),
-                schemaColumnBuilder.build()));
+          nameColumnBuilder.build(),
+          descriptionColumnBuilder.build(),
+          schemaColumnBuilder.build()));
+    }
+
+    /*
+     * Check if a string is a link to a reference, format <<_referenceClass>>
+      *
+     * @param possibleAnchor String to check
+     * @return true if the string is a link to an anchor, false otherwise
+     */
+    private boolean isReferenceLink(String possibleAnchor) {
+        return possibleAnchor.startsWith("<<_") && possibleAnchor.endsWith(">>");
+    }
+
+    public static class Parameters {
+        private final Map<String, Property> properties;
+        private final String parameterName;
+        private final List<ObjectType> inlineDefinitions;
+
+        public Parameters(Map<String, Property> properties,
+          String parameterName,
+          List<ObjectType> inlineDefinitions) {
+
+            this.properties = Validate.notNull(properties, "Properties must not be null");
+            this.parameterName = Validate.notBlank(parameterName, "ParameterName must not be blank");
+            this.inlineDefinitions = Validate.notNull(inlineDefinitions, "InlineDefinitions must not be null");
+        }
     }
 }

src/main/java/io/github/swagger2markup/internal/component/ResponseComponent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,7 +17,6 @@ package io.github.swagger2markup.internal.component;
 
 
 import ch.netzwerg.paleo.StringColumn;
-import io.github.swagger2markup.Labels;
 import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.internal.adapter.PropertyAdapter;
 import io.github.swagger2markup.internal.resolver.DocumentResolver;
@@ -49,43 +48,28 @@ public class ResponseComponent extends MarkupComponent<ResponseComponent.Paramet
     private final TableComponent tableComponent;
     private final DocumentResolver definitionDocumentResolver;
 
-    public ResponseComponent(Swagger2MarkupConverter.Context context,
-                             DocumentResolver definitionDocumentResolver){
+    ResponseComponent(Swagger2MarkupConverter.Context context,
+                      DocumentResolver definitionDocumentResolver) {
         super(context);
         this.definitionDocumentResolver = Validate.notNull(definitionDocumentResolver, "DocumentResolver must not be null");
         this.tableComponent = new TableComponent(context);
     }
 
     public static ResponseComponent.Parameters parameters(PathOperation operation,
-                                                                int titleLevel,
-                                                                List<ObjectType> inlineDefinitions){
+                                                          int titleLevel,
+                                                          List<ObjectType> inlineDefinitions) {
         return new ResponseComponent.Parameters(operation, titleLevel, inlineDefinitions);
     }
 
-    public static class Parameters {
-        private final PathOperation operation;
-        private final int titleLevel;
-        private final List<ObjectType> inlineDefinitions;
-
-        public Parameters(PathOperation operation,
-                          int titleLevel,
-                          List<ObjectType> inlineDefinitions){
-
-            this.operation = Validate.notNull(operation, "PathOperation must not be null");
-            this.titleLevel = titleLevel;
-            this.inlineDefinitions = Validate.notNull(inlineDefinitions, "InlineDefinitions must not be null");
-        }
-    }
-
     @Override
-    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params){
+    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params) {
         PathOperation operation = params.operation;
         Map<String, Response> responses = operation.getOperation().getResponses();
 
         MarkupDocBuilder responsesBuilder = copyMarkupDocBuilder(markupDocBuilder);
         applyPathsDocumentExtension(new PathsDocumentExtension.Context(PathsDocumentExtension.Position.OPERATION_RESPONSES_BEGIN, responsesBuilder, operation));
         if (MapUtils.isNotEmpty(responses)) {
-            StringColumn.Builder httpCodeColumnBuilder = StringColumn.builder(StringColumnId.of(labels.getLabel(Labels.HTTP_CODE_COLUMN)))
+            StringColumn.Builder httpCodeColumnBuilder = StringColumn.builder(StringColumnId.of(labels.getLabel(HTTP_CODE_COLUMN)))
                     .putMetaData(TableComponent.WIDTH_RATIO, "2");
             StringColumn.Builder descriptionColumnBuilder = StringColumn.builder(StringColumnId.of(labels.getLabel(DESCRIPTION_COLUMN)))
                     .putMetaData(TableComponent.WIDTH_RATIO, "14")
@@ -102,7 +86,7 @@ public class ResponseComponent extends MarkupComponent<ResponseComponent.Paramet
                     Type type = new PropertyAdapter(property).getType(definitionDocumentResolver);
 
                     if (config.isInlineSchemaEnabled()) {
-                        type = createInlineType(type, labels.getLabel(Labels.RESPONSE) + " " + responseName, operation.getId() + " " + labels.getLabel(Labels.RESPONSE) + " " + responseName, params.inlineDefinitions);
+                        type = createInlineType(type, labels.getLabel(RESPONSE) + " " + responseName, operation.getId() + " " + labels.getLabel(RESPONSE) + " " + responseName, params.inlineDefinitions);
                     }
 
                     schemaContent = type.displaySchema(markupDocBuilder);
@@ -114,12 +98,12 @@ public class ResponseComponent extends MarkupComponent<ResponseComponent.Paramet
 
                 Map<String, Property> headers = response.getHeaders();
                 if (MapUtils.isNotEmpty(headers)) {
-                    descriptionBuilder.newLine(true).boldText(labels.getLabel(Labels.HEADERS_COLUMN)).text(COLON);
+                    descriptionBuilder.newLine(true).boldText(labels.getLabel(HEADERS_COLUMN)).text(COLON);
                     for (Map.Entry<String, Property> header : headers.entrySet()) {
                         descriptionBuilder.newLine(true);
                         Property headerProperty = header.getValue();
                         PropertyAdapter headerPropertyAdapter = new PropertyAdapter(headerProperty);
-                        Type propertyType = headerPropertyAdapter.getType(null);
+                        Type propertyType = headerPropertyAdapter.getType(definitionDocumentResolver);
                         String headerDescription = markupDescription(config.getSwaggerMarkupLanguage(), markupDocBuilder, headerProperty.getDescription());
                         Optional<Object> optionalDefaultValue = headerPropertyAdapter.getDefaultValue();
 
@@ -135,9 +119,9 @@ public class ResponseComponent extends MarkupComponent<ResponseComponent.Paramet
 
                             descriptionBuilder.text(headerDescription);
 
-                            if (optionalDefaultValue.isPresent()) {
-                                descriptionBuilder.text(" ").boldText(labels.getLabel(DEFAULT_COLUMN)).text(COLON).literalText(Json.pretty(optionalDefaultValue.get()));
-                            }
+                            optionalDefaultValue.ifPresent(o -> descriptionBuilder.text(" ")
+                                    .boldText(labels.getLabel(DEFAULT_COLUMN))
+                                    .text(COLON).literalText(Json.pretty(o)));
                         }
                     }
                 }
@@ -156,7 +140,7 @@ public class ResponseComponent extends MarkupComponent<ResponseComponent.Paramet
 
         applyPathsDocumentExtension(new PathsDocumentExtension.Context(PathsDocumentExtension.Position.OPERATION_RESPONSES_BEFORE, markupDocBuilder, operation));
         if (isNotBlank(responsesContent)) {
-            markupDocBuilder.sectionTitleLevel(params.titleLevel, labels.getLabel(Labels.RESPONSES));
+            markupDocBuilder.sectionTitleLevel(params.titleLevel, labels.getLabel(RESPONSES));
             markupDocBuilder.text(responsesContent);
         }
         applyPathsDocumentExtension(new PathsDocumentExtension.Context(PathsDocumentExtension.Position.OPERATION_RESPONSES_AFTER, markupDocBuilder, operation));
@@ -171,4 +155,19 @@ public class ResponseComponent extends MarkupComponent<ResponseComponent.Paramet
     private void applyPathsDocumentExtension(PathsDocumentExtension.Context context) {
         extensionRegistry.getPathsDocumentExtensions().forEach(extension -> extension.apply(context));
     }
+
+    public static class Parameters {
+        private final PathOperation operation;
+        private final int titleLevel;
+        private final List<ObjectType> inlineDefinitions;
+
+        public Parameters(PathOperation operation,
+                          int titleLevel,
+                          List<ObjectType> inlineDefinitions) {
+
+            this.operation = Validate.notNull(operation, "PathOperation must not be null");
+            this.titleLevel = titleLevel;
+            this.inlineDefinitions = Validate.notNull(inlineDefinitions, "InlineDefinitions must not be null");
+        }
+    }
 }

src/main/java/io/github/swagger2markup/internal/component/SecuritySchemeComponent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -33,9 +33,7 @@ import java.util.Map;
 
 import static ch.netzwerg.paleo.ColumnIds.StringColumnId;
 import static io.github.swagger2markup.Labels.*;
-import static io.github.swagger2markup.internal.utils.MarkupDocBuilderUtils.boldText;
-import static io.github.swagger2markup.internal.utils.MarkupDocBuilderUtils.copyMarkupDocBuilder;
-import static io.github.swagger2markup.internal.utils.MarkupDocBuilderUtils.crossReference;
+import static io.github.swagger2markup.internal.utils.MarkupDocBuilderUtils.*;
 import static org.apache.commons.lang3.StringUtils.isNotBlank;
 
 public class SecuritySchemeComponent extends MarkupComponent<SecuritySchemeComponent.Parameters> {
@@ -45,32 +43,20 @@ public class SecuritySchemeComponent extends MarkupComponent<SecuritySchemeCompo
     private final TableComponent tableComponent;
 
     public SecuritySchemeComponent(Swagger2MarkupConverter.Context context,
-                                   DocumentResolver securityDocumentResolver){
+                                   DocumentResolver securityDocumentResolver) {
         super(context);
         this.securityDefinitions = context.getSwagger().getSecurityDefinitions();
         this.securityDocumentResolver = Validate.notNull(securityDocumentResolver, "SecurityDocumentResolver must not be null");
         this.tableComponent = new TableComponent(context);
     }
 
-    public static class Parameters {
-        private final PathOperation operation;
-        private final int titleLevel;
-
-        public Parameters(PathOperation operation,
-                          int titleLevel){
-            this.operation = Validate.notNull(operation, "PathOperation must not be null");
-            this.titleLevel = titleLevel;
-        }
-    }
-
     public static SecuritySchemeComponent.Parameters parameters(PathOperation operation,
-                                                                 int titleLevel){
+                                                                int titleLevel) {
         return new SecuritySchemeComponent.Parameters(operation, titleLevel);
     }
 
-
     @Override
-    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params){
+    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params) {
         PathOperation operation = params.operation;
         MarkupDocBuilder securityBuilder = copyMarkupDocBuilder(markupDocBuilder);
         List<Map<String, List<String>>> securitySchemes = operation.getOperation().getSecurity();
@@ -123,4 +109,15 @@ public class SecuritySchemeComponent extends MarkupComponent<SecuritySchemeCompo
     private void applyPathsDocumentExtension(PathsDocumentExtension.Context context) {
         extensionRegistry.getPathsDocumentExtensions().forEach(extension -> extension.apply(context));
     }
+
+    public static class Parameters {
+        private final PathOperation operation;
+        private final int titleLevel;
+
+        public Parameters(PathOperation operation,
+                          int titleLevel) {
+            this.operation = Validate.notNull(operation, "PathOperation must not be null");
+            this.titleLevel = titleLevel;
+        }
+    }
 }

src/main/java/io/github/swagger2markup/internal/component/SecuritySchemeDefinitionComponent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -39,33 +39,19 @@ public class SecuritySchemeDefinitionComponent extends MarkupComponent<SecurityS
 
     private final TableComponent tableComponent;
 
-    public SecuritySchemeDefinitionComponent(Swagger2MarkupConverter.Context context){
+    public SecuritySchemeDefinitionComponent(Swagger2MarkupConverter.Context context) {
         super(context);
         this.tableComponent = new TableComponent(context);
     }
 
-    public static class Parameters {
-        private final String securitySchemeDefinitionName;
-        private final SecuritySchemeDefinition securitySchemeDefinition;
-        private final int titleLevel;
-
-        public Parameters(String securitySchemeDefinitionName,
-                          SecuritySchemeDefinition securitySchemeDefinition,
-                          int titleLevel){
-            this.securitySchemeDefinitionName = Validate.notBlank(securitySchemeDefinitionName, "SecuritySchemeDefinitionName must not be empty");
-            this.securitySchemeDefinition = Validate.notNull(securitySchemeDefinition, "SecuritySchemeDefinition must not be null");
-            this.titleLevel = titleLevel;
-        }
-    }
-
     public static SecuritySchemeDefinitionComponent.Parameters parameters(String securitySchemeDefinitionName,
                                                                           SecuritySchemeDefinition securitySchemeDefinition,
-                                                                          int titleLevel){
+                                                                          int titleLevel) {
         return new SecuritySchemeDefinitionComponent.Parameters(securitySchemeDefinitionName, securitySchemeDefinition, titleLevel);
     }
 
     @Override
-    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params){
+    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params) {
         String securitySchemeDefinitionName = params.securitySchemeDefinitionName;
         SecuritySchemeDefinition securitySchemeDefinition = params.securitySchemeDefinition;
         applySecurityDocumentExtension(new SecurityDocumentExtension.Context(Position.SECURITY_SCHEME_BEFORE, markupDocBuilder, securitySchemeDefinitionName, securitySchemeDefinition));
@@ -109,7 +95,7 @@ public class SecuritySchemeDefinitionComponent extends MarkupComponent<SecurityS
                     .putMetaData(TableComponent.WIDTH_RATIO, "17")
                     .putMetaData(TableComponent.HEADER_COLUMN, "true");
 
-            if(oauth2Scheme.getScopes() != null) {
+            if (oauth2Scheme.getScopes() != null) {
                 for (Map.Entry<String, String> scope : oauth2Scheme.getScopes().entrySet()) {
                     nameColumnBuilder.add(scope.getKey());
                     descriptionColumnBuilder.add(scope.getValue());
@@ -132,4 +118,18 @@ public class SecuritySchemeDefinitionComponent extends MarkupComponent<SecurityS
     private void applySecurityDocumentExtension(SecurityDocumentExtension.Context context) {
         extensionRegistry.getSecurityDocumentExtensions().forEach(extension -> extension.apply(context));
     }
+
+    public static class Parameters {
+        private final String securitySchemeDefinitionName;
+        private final SecuritySchemeDefinition securitySchemeDefinition;
+        private final int titleLevel;
+
+        public Parameters(String securitySchemeDefinitionName,
+                          SecuritySchemeDefinition securitySchemeDefinition,
+                          int titleLevel) {
+            this.securitySchemeDefinitionName = Validate.notBlank(securitySchemeDefinitionName, "SecuritySchemeDefinitionName must not be empty");
+            this.securitySchemeDefinition = Validate.notNull(securitySchemeDefinition, "SecuritySchemeDefinition must not be null");
+            this.titleLevel = titleLevel;
+        }
+    }
 }

src/main/java/io/github/swagger2markup/internal/component/TableComponent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -33,27 +33,20 @@ public class TableComponent extends MarkupComponent<TableComponent.Parameters> {
     public static final String WIDTH_RATIO = "widthRatio";
     public static final String HEADER_COLUMN = "headerColumn";
 
-    public TableComponent(Swagger2MarkupConverter.Context context){
+    public TableComponent(Swagger2MarkupConverter.Context context) {
         super(context);
     }
 
-    public static TableComponent.Parameters parameters(StringColumn... columns){
+    public static TableComponent.Parameters parameters(StringColumn... columns) {
         return new TableComponent.Parameters(columns);
     }
 
-    public static class Parameters {
-        private final DataFrame dataFrame;
-        public Parameters(StringColumn... columns){
-            this.dataFrame = DataFrame.ofAll(List.of(columns).filter(TableComponent::isNotBlank));
-        }
-    }
-
     public static boolean isNotBlank(StringColumn column) {
         return !column.getValues().filter(StringUtils::isNotBlank).isEmpty();
     }
 
     @Override
-    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params){
+    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params) {
         DataFrame dataFrame = params.dataFrame;
         java.util.List<MarkupTableColumn> columnSpecs = dataFrame.getColumns().map(column -> {
                     Integer widthRatio = Integer.valueOf(column.getMetaData().get(WIDTH_RATIO).getOrElse("0"));
@@ -72,4 +65,12 @@ public class TableComponent extends MarkupComponent<TableComponent.Parameters> {
 
         return markupDocBuilder.tableWithColumnSpecs(columnSpecs, cells);
     }
+
+    public static class Parameters {
+        private final DataFrame dataFrame;
+
+        public Parameters(StringColumn... columns) {
+            this.dataFrame = DataFrame.ofAll(List.of(columns).filter(TableComponent::isNotBlank));
+        }
+    }
 }

src/main/java/io/github/swagger2markup/internal/component/TagsComponent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,8 +16,8 @@
 package io.github.swagger2markup.internal.component;
 
 
-import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.Labels;
+import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
 import io.github.swagger2markup.spi.MarkupComponent;
 import io.swagger.models.Tag;
@@ -31,29 +31,17 @@ import static org.apache.commons.lang3.StringUtils.isNotBlank;
 
 public class TagsComponent extends MarkupComponent<TagsComponent.Parameters> {
 
-    public TagsComponent(Swagger2MarkupConverter.Context context){
+    public TagsComponent(Swagger2MarkupConverter.Context context) {
         super(context);
     }
 
     public static TagsComponent.Parameters parameters(List<Tag> tags,
-                                                      int titleLevel){
+                                                      int titleLevel) {
         return new TagsComponent.Parameters(tags, titleLevel);
     }
 
-    public static class Parameters {
-
-        private final List<Tag> tags;
-        private final int titleLevel;
-
-        public Parameters(List<Tag> tags,
-                          int titleLevel){
-            this.tags = Validate.notNull(tags, "Tags must not be null");
-            this.titleLevel = titleLevel;
-        }
-    }
-
     @Override
-    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params){
+    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params) {
         markupDocBuilder.sectionTitleLevel(params.titleLevel, labels.getLabel(Labels.TAGS));
 
         List<String> tagsList = params.tags.stream()
@@ -67,13 +55,25 @@ public class TagsComponent extends MarkupComponent<TagsComponent.Parameters> {
         return markupDocBuilder;
     }
 
-    private String mapToString(Tag tag){
+    private String mapToString(Tag tag) {
         String name = tag.getName();
         String description = tag.getDescription();
-        if(isNotBlank(description)){
+        if (isNotBlank(description)) {
             return name + COLON + description;
-        }else{
+        } else {
             return name;
         }
     }
+
+    public static class Parameters {
+
+        private final List<Tag> tags;
+        private final int titleLevel;
+
+        public Parameters(List<Tag> tags,
+                          int titleLevel) {
+            this.tags = Validate.notNull(tags, "Tags must not be null");
+            this.titleLevel = titleLevel;
+        }
+    }
 }

src/main/java/io/github/swagger2markup/internal/component/UriSchemeComponent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -33,30 +33,18 @@ import static org.apache.commons.lang3.StringUtils.join;
 public class UriSchemeComponent extends MarkupComponent<UriSchemeComponent.Parameters> {
 
 
-    public UriSchemeComponent(Swagger2MarkupConverter.Context context){
+    public UriSchemeComponent(Swagger2MarkupConverter.Context context) {
         super(context);
     }
 
-    public static UriSchemeComponent.Parameters parameters(Swagger swagger, int titleLevel){
+    public static UriSchemeComponent.Parameters parameters(Swagger swagger, int titleLevel) {
         return new UriSchemeComponent.Parameters(swagger, titleLevel);
     }
 
-    public static class Parameters {
-
-        private final int titleLevel;
-        private final Swagger swagger;
-
-        public Parameters(Swagger swagger, int titleLevel){
-
-            this.swagger = Validate.notNull(swagger);
-            this.titleLevel = titleLevel;
-        }
-    }
-
     @Override
-    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params){
+    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params) {
         Swagger swagger = params.swagger;
-        if(isNotBlank(swagger.getHost()) || isNotBlank(swagger.getBasePath()) || isNotEmpty(swagger.getSchemes())) {
+        if (isNotBlank(swagger.getHost()) || isNotBlank(swagger.getBasePath()) || isNotEmpty(swagger.getSchemes())) {
             markupDocBuilder.sectionTitleLevel(params.titleLevel, labels.getLabel(Labels.URI_SCHEME));
             MarkupDocBuilder paragraphBuilder = copyMarkupDocBuilder(markupDocBuilder);
             if (isNotBlank(swagger.getHost())) {
@@ -79,5 +67,17 @@ public class UriSchemeComponent extends MarkupComponent<UriSchemeComponent.Param
         return markupDocBuilder;
     }
 
+    public static class Parameters {
+
+        private final int titleLevel;
+        private final Swagger swagger;
+
+        public Parameters(Swagger swagger, int titleLevel) {
+
+            this.swagger = Validate.notNull(swagger);
+            this.titleLevel = titleLevel;
+        }
+    }
+
 
 }

src/main/java/io/github/swagger2markup/internal/component/VersionInfoComponent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,8 +15,8 @@
  */
 package io.github.swagger2markup.internal.component;
 
-import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.Labels;
+import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
 import io.github.swagger2markup.spi.MarkupComponent;
 import io.swagger.models.Info;
@@ -28,16 +28,27 @@ import static org.apache.commons.lang3.StringUtils.isNotBlank;
 public class VersionInfoComponent extends MarkupComponent<VersionInfoComponent.Parameters> {
 
 
-
-    public VersionInfoComponent(Swagger2MarkupConverter.Context context){
+    public VersionInfoComponent(Swagger2MarkupConverter.Context context) {
         super(context);
     }
 
     public static VersionInfoComponent.Parameters parameters(Info info,
-                                                           int titleLevel){
+                                                             int titleLevel) {
         return new VersionInfoComponent.Parameters(info, titleLevel);
     }
 
+    @Override
+    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params) {
+        String version = params.info.getVersion();
+        if (isNotBlank(version)) {
+            markupDocBuilder.sectionTitleLevel(params.titleLevel, labels.getLabel(Labels.CURRENT_VERSION));
+            MarkupDocBuilder paragraphBuilder = copyMarkupDocBuilder(markupDocBuilder);
+            paragraphBuilder.italicText(labels.getLabel(Labels.VERSION)).textLine(COLON + version);
+            markupDocBuilder.paragraph(paragraphBuilder.toString(), true);
+        }
+        return markupDocBuilder;
+    }
+
     public static class Parameters {
 
         private final int titleLevel;
@@ -45,21 +56,9 @@ public class VersionInfoComponent extends MarkupComponent<VersionInfoComponent.P
 
         public Parameters(
                 Info info,
-                int titleLevel){
+                int titleLevel) {
             this.info = Validate.notNull(info, "Info must not be null");
             this.titleLevel = titleLevel;
         }
     }
-
-    @Override
-    public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params){
-        String version = params.info.getVersion();
-        if(isNotBlank(version)){
-            markupDocBuilder.sectionTitleLevel(params.titleLevel, labels.getLabel(Labels.CURRENT_VERSION));
-            MarkupDocBuilder paragraphBuilder = copyMarkupDocBuilder(markupDocBuilder);
-            paragraphBuilder.italicText(labels.getLabel(Labels.VERSION)).textLine(COLON + version);
-            markupDocBuilder.paragraph(paragraphBuilder.toString(), true);
-        }
-        return markupDocBuilder;
-    }
 }

src/main/java/io/github/swagger2markup/internal/document/DefinitionsDocument.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,9 +18,9 @@ package io.github.swagger2markup.internal.document;
 import io.github.swagger2markup.Labels;
 import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.internal.component.DefinitionComponent;
+import io.github.swagger2markup.internal.resolver.DefinitionDocumentNameResolver;
 import io.github.swagger2markup.internal.resolver.DefinitionDocumentResolverDefault;
 import io.github.swagger2markup.internal.resolver.DefinitionDocumentResolverFromDefinition;
-import io.github.swagger2markup.internal.resolver.DefinitionDocumentNameResolver;
 import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
 import io.github.swagger2markup.spi.MarkupComponent;
 import io.swagger.models.Model;
@@ -43,7 +43,7 @@ import static org.apache.commons.lang3.StringUtils.isNotBlank;
  * @author Robert Winkler
  */
 public class DefinitionsDocument extends MarkupComponent<DefinitionsDocument.Parameters> {
-    
+
     private static final String DEFINITIONS_ANCHOR = "definitions";
 
     private static final List<String> IGNORED_DEFINITIONS = Collections.singletonList("Void");
@@ -67,18 +67,10 @@ public class DefinitionsDocument extends MarkupComponent<DefinitionsDocument.Par
         this.definitionDocumentResolverDefault = new DefinitionDocumentResolverDefault(context);
     }
 
-    public static DefinitionsDocument.Parameters parameters(Map<String, Model> definitions){
+    public static DefinitionsDocument.Parameters parameters(Map<String, Model> definitions) {
         return new DefinitionsDocument.Parameters(definitions);
     }
 
-    public static class Parameters {
-        private final Map<String, Model> definitions;
-
-        public Parameters(Map<String, Model> definitions){
-            this.definitions = definitions;
-        }
-    }
-
     /**
      * Builds the definitions MarkupDocument.
      *
@@ -105,8 +97,8 @@ public class DefinitionsDocument extends MarkupComponent<DefinitionsDocument.Par
     private void buildDefinitionsSection(MarkupDocBuilder markupDocBuilder, Map<String, Model> definitions) {
         Map<String, Model> sortedMap = toSortedMap(definitions, config.getDefinitionOrdering());
         sortedMap.forEach((String definitionName, Model model) -> {
-            if(isNotBlank(definitionName)
-                    && checkThatDefinitionIsNotInIgnoreList(definitionName)){
+            if (isNotBlank(definitionName)
+                    && checkThatDefinitionIsNotInIgnoreList(definitionName)) {
                 buildDefinition(markupDocBuilder, definitionName, model);
             }
         });
@@ -128,16 +120,16 @@ public class DefinitionsDocument extends MarkupComponent<DefinitionsDocument.Par
      * @param model          definition model to process
      */
     private void buildDefinition(MarkupDocBuilder markupDocBuilder, String definitionName, Model model) {
-        if (logger.isInfoEnabled()) {
-            logger.info("Definition processed : '{}'", definitionName);
+        if (logger.isDebugEnabled()) {
+            logger.debug("Definition processed : '{}'", definitionName);
         }
         if (config.isSeparatedDefinitionsEnabled()) {
             MarkupDocBuilder defDocBuilder = copyMarkupDocBuilder(markupDocBuilder);
             applyDefinitionComponent(defDocBuilder, definitionName, model);
             Path definitionFile = context.getOutputPath().resolve(definitionDocumentNameResolver.apply(definitionName));
             defDocBuilder.writeToFileWithoutExtension(definitionFile, StandardCharsets.UTF_8);
-            if (logger.isInfoEnabled()) {
-                logger.info("Separate definition file produced : '{}'", definitionFile);
+            if (logger.isDebugEnabled()) {
+                logger.debug("Separate definition file produced : '{}'", definitionFile);
             }
 
             definitionRef(markupDocBuilder, definitionName);
@@ -160,9 +152,9 @@ public class DefinitionsDocument extends MarkupComponent<DefinitionsDocument.Par
     /**
      * Builds a concrete definition
      *
-     * @param markupDocBuilder  the markupDocBuilder do use for output
-     * @param definitionName the name of the definition
-     * @param model          the Swagger Model of the definition
+     * @param markupDocBuilder the markupDocBuilder do use for output
+     * @param definitionName   the name of the definition
+     * @param model            the Swagger Model of the definition
      */
     private void applyDefinitionComponent(MarkupDocBuilder markupDocBuilder, String definitionName, Model model) {
         definitionComponent.apply(markupDocBuilder, DefinitionComponent.parameters(
@@ -182,13 +174,21 @@ public class DefinitionsDocument extends MarkupComponent<DefinitionsDocument.Par
 
     /**
      * Builds definition title
-
+     *
      * @param markupDocBuilder the markupDocBuilder do use for output
-     * @param title      definition title
-     * @param anchor     optional anchor (null => auto-generate from title)
+     * @param title            definition title
+     * @param anchor           optional anchor (null => auto-generate from title)
      */
     private void buildDefinitionTitle(MarkupDocBuilder markupDocBuilder, String title, String anchor) {
         markupDocBuilder.sectionTitleWithAnchorLevel2(title, anchor);
     }
 
+    public static class Parameters {
+        private final Map<String, Model> definitions;
+
+        public Parameters(Map<String, Model> definitions) {
+            this.definitions = definitions;
+        }
+    }
+
 }

src/main/java/io/github/swagger2markup/internal/document/OverviewDocument.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -20,10 +20,7 @@ import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.internal.component.*;
 import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
 import io.github.swagger2markup.spi.MarkupComponent;
-import io.swagger.models.Contact;
-import io.swagger.models.Info;
-import io.swagger.models.Swagger;
-import io.swagger.models.Tag;
+import io.swagger.models.*;
 import org.apache.commons.lang3.Validate;
 
 import java.util.List;
@@ -36,8 +33,8 @@ import static org.apache.commons.lang3.StringUtils.isNotBlank;
 
 public class OverviewDocument extends MarkupComponent<OverviewDocument.Parameters> {
 
-    private static final String OVERVIEW_ANCHOR = "overview";
     public static final int SECTION_TITLE_LEVEL = 2;
+    private static final String OVERVIEW_ANCHOR = "overview";
     private final VersionInfoComponent versionInfoComponent;
     private final ContactInfoComponent contactInfoComponent;
     private final LicenseInfoComponent licenseInfoComponent;
@@ -45,8 +42,9 @@ public class OverviewDocument extends MarkupComponent<OverviewDocument.Parameter
     private final TagsComponent tagsComponent;
     private final ProducesComponent producesComponent;
     private final ConsumesComponent consumesComponent;
+    private final ExternalDocsComponent externalDocsComponent;
 
-    public OverviewDocument(Swagger2MarkupConverter.Context context){
+    public OverviewDocument(Swagger2MarkupConverter.Context context) {
         super(context);
         versionInfoComponent = new VersionInfoComponent(context);
         contactInfoComponent = new ContactInfoComponent(context);
@@ -55,20 +53,13 @@ public class OverviewDocument extends MarkupComponent<OverviewDocument.Parameter
         tagsComponent = new TagsComponent(context);
         producesComponent = new ProducesComponent(context);
         consumesComponent = new ConsumesComponent(context);
+	    externalDocsComponent = new ExternalDocsComponent((context));
     }
 
-    public static OverviewDocument.Parameters parameters(Swagger swagger){
+    public static OverviewDocument.Parameters parameters(Swagger swagger) {
         return new OverviewDocument.Parameters(swagger);
     }
 
-    public static class Parameters {
-        private final Swagger swagger;
-
-        public Parameters(Swagger swagger){
-            this.swagger = Validate.notNull(swagger, "Swagger must not be null");
-        }
-    }
-
     /**
      * Builds the overview MarkupDocument.
      *
@@ -90,6 +81,7 @@ public class OverviewDocument extends MarkupComponent<OverviewDocument.Parameter
         buildTagsSection(markupDocBuilder, swagger.getTags());
         buildConsumesSection(markupDocBuilder, swagger.getConsumes());
         buildProducesSection(markupDocBuilder, swagger.getProduces());
+        buildExternalDocsSection(markupDocBuilder, swagger.getExternalDocs());
         applyOverviewDocumentExtension(new Context(Position.DOCUMENT_END, markupDocBuilder));
         applyOverviewDocumentExtension(new Context(Position.DOCUMENT_AFTER, markupDocBuilder));
         return markupDocBuilder;
@@ -116,7 +108,7 @@ public class OverviewDocument extends MarkupComponent<OverviewDocument.Parameter
     }
 
     private void buildContactInfoSection(MarkupDocBuilder markupDocBuilder, Contact contact) {
-        if(contact != null){
+        if (contact != null) {
             contactInfoComponent.apply(markupDocBuilder, ContactInfoComponent.parameters(contact, SECTION_TITLE_LEVEL));
         }
     }
@@ -132,14 +124,14 @@ public class OverviewDocument extends MarkupComponent<OverviewDocument.Parameter
     }
 
     private void buildTagsSection(MarkupDocBuilder markupDocBuilder, List<Tag> tags) {
-        if(isNotEmpty(tags)){
+        if (isNotEmpty(tags)) {
             tagsComponent.apply(markupDocBuilder, TagsComponent.parameters(tags, SECTION_TITLE_LEVEL));
         }
     }
 
     private void buildConsumesSection(MarkupDocBuilder markupDocBuilder, List<String> consumes) {
         if (isNotEmpty(consumes)) {
-            consumesComponent.apply(markupDocBuilder, ConsumesComponent.parameters(consumes, SECTION_TITLE_LEVEL));;
+            consumesComponent.apply(markupDocBuilder, ConsumesComponent.parameters(consumes, SECTION_TITLE_LEVEL));
         }
     }
 
@@ -149,6 +141,12 @@ public class OverviewDocument extends MarkupComponent<OverviewDocument.Parameter
         }
     }
 
+    private void buildExternalDocsSection(MarkupDocBuilder markupDocBuilder, ExternalDocs externalDocs) {
+	    if (externalDocs != null) {
+	    	externalDocsComponent.apply(markupDocBuilder, ExternalDocsComponent.parameters(externalDocs, SECTION_TITLE_LEVEL));
+	    }
+    }
+
     /**
      * Apply extension context to all OverviewContentExtension
      *
@@ -158,4 +156,12 @@ public class OverviewDocument extends MarkupComponent<OverviewDocument.Parameter
         extensionRegistry.getOverviewDocumentExtensions().forEach(extension -> extension.apply(context));
     }
 
+    public static class Parameters {
+        private final Swagger swagger;
+
+        public Parameters(Swagger swagger) {
+            this.swagger = Validate.notNull(swagger, "Swagger must not be null");
+        }
+    }
+
 }

src/main/java/io/github/swagger2markup/internal/document/PathsDocument.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,6 +18,7 @@ package io.github.swagger2markup.internal.document;
 import com.google.common.collect.Multimap;
 import io.github.swagger2markup.GroupBy;
 import io.github.swagger2markup.Labels;
+import io.github.swagger2markup.Swagger2MarkupConfig;
 import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.internal.component.PathOperationComponent;
 import io.github.swagger2markup.internal.resolver.DefinitionDocumentResolverFromOperation;
@@ -25,6 +26,7 @@ import io.github.swagger2markup.internal.resolver.OperationDocumentNameResolver;
 import io.github.swagger2markup.internal.resolver.OperationDocumentResolverDefault;
 import io.github.swagger2markup.internal.resolver.SecurityDocumentResolver;
 import io.github.swagger2markup.internal.utils.PathUtils;
+import io.github.swagger2markup.internal.utils.RegexUtils;
 import io.github.swagger2markup.internal.utils.TagUtils;
 import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
 import io.github.swagger2markup.model.PathOperation;
@@ -40,6 +42,8 @@ import org.apache.commons.lang3.text.WordUtils;
 import java.nio.charset.StandardCharsets;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
+import java.util.regex.Pattern;
 
 import static io.github.swagger2markup.internal.utils.MarkupDocBuilderUtils.copyMarkupDocBuilder;
 import static io.github.swagger2markup.internal.utils.MarkupDocBuilderUtils.crossReference;
@@ -65,39 +69,25 @@ public class PathsDocument extends MarkupComponent<PathsDocument.Parameters> {
         this.operationDocumentNameResolver = new OperationDocumentNameResolver(context);
         this.operationDocumentResolverDefault = new OperationDocumentResolverDefault(context);
 
-        if (config.isGeneratedExamplesEnabled()) {
-            if (logger.isDebugEnabled()) {
+        if (logger.isDebugEnabled()) {
+            if (config.isGeneratedExamplesEnabled()) {
                 logger.debug("Generate examples is enabled.");
-            }
-        } else {
-            if (logger.isDebugEnabled()) {
+            } else {
                 logger.debug("Generate examples is disabled.");
             }
-        }
 
-        if (config.isSeparatedOperationsEnabled()) {
-            if (logger.isDebugEnabled()) {
+            if (config.isSeparatedOperationsEnabled()) {
                 logger.debug("Create separated operation files is enabled.");
-            }
-        } else {
-            if (logger.isDebugEnabled()) {
+            } else {
                 logger.debug("Create separated operation files is disabled.");
             }
         }
     }
 
-    public static PathsDocument.Parameters parameters(Map<String, Path> paths){
+    public static PathsDocument.Parameters parameters(Map<String, Path> paths) {
         return new PathsDocument.Parameters(paths);
     }
 
-    public static class Parameters {
-        private final Map<String, Path> paths;
-
-        public Parameters(Map<String, Path> paths){
-            this.paths = paths;
-        }
-    }
-
     /**
      * Builds the paths MarkupDocument.
      *
@@ -118,7 +108,7 @@ public class PathsDocument extends MarkupComponent<PathsDocument.Parameters> {
     }
 
     /**
-     * Builds the paths section. Groups the paths either as-is or by tags.
+     * Builds the paths section. Groups the paths either as-is, by tags or using regex.
      *
      * @param paths the Swagger paths
      */
@@ -126,8 +116,8 @@ public class PathsDocument extends MarkupComponent<PathsDocument.Parameters> {
         List<PathOperation> pathOperations = PathUtils.toPathOperationsList(paths, getBasePath(), config.getOperationOrdering());
         if (CollectionUtils.isNotEmpty(pathOperations)) {
             if (config.getPathsGroupedBy() == GroupBy.AS_IS) {
-                pathOperations.forEach(operation -> buildOperation(markupDocBuilder, operation));
-            } else {
+                pathOperations.forEach(operation -> buildOperation(markupDocBuilder, operation, config));
+            } else if (config.getPathsGroupedBy() == GroupBy.TAGS) {
                 Validate.notEmpty(context.getSwagger().getTags(), "Tags must not be empty, when operations are grouped by tags");
                 // Group operations by tag
                 Multimap<String, PathOperation> operationsGroupedByTag = TagUtils.groupOperationsByTag(pathOperations, config.getOperationOrdering());
@@ -137,12 +127,24 @@ public class PathsDocument extends MarkupComponent<PathsDocument.Parameters> {
                 tagsMap.forEach((String tagName, Tag tag) -> {
                     markupDocBuilder.sectionTitleWithAnchorLevel2(WordUtils.capitalize(tagName), tagName + "_resource");
                     String description = tag.getDescription();
-                    if(StringUtils.isNotBlank(description)){
+                    if (StringUtils.isNotBlank(description)) {
                         markupDocBuilder.paragraph(description);
                     }
-                    operationsGroupedByTag.get(tagName).forEach(operation -> buildOperation(markupDocBuilder, operation));
+                    operationsGroupedByTag.get(tagName).forEach(operation -> buildOperation(markupDocBuilder, operation, config));
 
                 });
+            } else if (config.getPathsGroupedBy() == GroupBy.REGEX) {
+                Validate.notNull(config.getHeaderPattern(), "Header regex pattern must not be empty when operations are grouped using regex");
+
+                Pattern headerPattern = config.getHeaderPattern();
+                Multimap<String, PathOperation> operationsGroupedByRegex = RegexUtils.groupOperationsByRegex(pathOperations, headerPattern);
+                Set<String> keys = operationsGroupedByRegex.keySet();
+                String[] sortedHeaders = RegexUtils.toSortedArray(keys);
+
+                for (String header : sortedHeaders) {
+                    markupDocBuilder.sectionTitleWithAnchorLevel2(WordUtils.capitalize(header), header + "_resource");
+                    operationsGroupedByRegex.get(header).forEach(operation -> buildOperation(markupDocBuilder, operation, config));
+                }
             }
         }
     }
@@ -153,6 +155,8 @@ public class PathsDocument extends MarkupComponent<PathsDocument.Parameters> {
     private void buildPathsTitle(MarkupDocBuilder markupDocBuilder) {
         if (config.getPathsGroupedBy() == GroupBy.AS_IS) {
             buildPathsTitle(markupDocBuilder, labels.getLabel(Labels.PATHS));
+        } else if (config.getPathsGroupedBy() == GroupBy.REGEX) {
+            buildPathsTitle(markupDocBuilder, labels.getLabel(Labels.OPERATIONS));
         } else {
             buildPathsTitle(markupDocBuilder, labels.getLabel(Labels.RESOURCES));
         }
@@ -164,7 +168,7 @@ public class PathsDocument extends MarkupComponent<PathsDocument.Parameters> {
      * @return either the relative or the full path
      */
     private String getBasePath() {
-        if(config.isBasePathPrefixEnabled()){
+        if (config.isBasePathPrefixEnabled()) {
             return StringUtils.defaultString(context.getSwagger().getBasePath());
         }
         return "";
@@ -188,14 +192,14 @@ public class PathsDocument extends MarkupComponent<PathsDocument.Parameters> {
      *
      * @param operation operation
      */
-    private void buildOperation(MarkupDocBuilder markupDocBuilder, PathOperation operation) {
+    private void buildOperation(MarkupDocBuilder markupDocBuilder, PathOperation operation, Swagger2MarkupConfig config) {
         if (config.isSeparatedOperationsEnabled()) {
             MarkupDocBuilder pathDocBuilder = copyMarkupDocBuilder(markupDocBuilder);
             applyPathOperationComponent(pathDocBuilder, operation);
             java.nio.file.Path operationFile = context.getOutputPath().resolve(operationDocumentNameResolver.apply(operation));
             pathDocBuilder.writeToFileWithoutExtension(operationFile, StandardCharsets.UTF_8);
-            if (logger.isInfoEnabled()) {
-                logger.info("Separate operation file produced : '{}'", operationFile);
+            if (logger.isDebugEnabled()) {
+                logger.debug("Separate operation file produced : '{}'", operationFile);
             }
             buildOperationRef(markupDocBuilder, operation);
 
@@ -203,8 +207,8 @@ public class PathsDocument extends MarkupComponent<PathsDocument.Parameters> {
             applyPathOperationComponent(markupDocBuilder, operation);
         }
 
-        if (logger.isInfoEnabled()) {
-            logger.info("Operation processed : '{}' (normalized id = '{}')", operation, normalizeName(operation.getId()));
+        if (logger.isDebugEnabled()) {
+            logger.debug("Operation processed : '{}' (normalized id = '{}')", operation, normalizeName(operation.getId()));
         }
     }
 
@@ -212,8 +216,7 @@ public class PathsDocument extends MarkupComponent<PathsDocument.Parameters> {
      * Builds a path operation.
      *
      * @param markupDocBuilder the docbuilder do use for output
-     * @param operation  the Swagger Operation
-     *
+     * @param operation        the Swagger Operation
      */
     private void applyPathOperationComponent(MarkupDocBuilder markupDocBuilder, PathOperation operation) {
         if (operation != null) {
@@ -225,7 +228,7 @@ public class PathsDocument extends MarkupComponent<PathsDocument.Parameters> {
      * Builds a cross-reference to a separated operation file
      *
      * @param markupDocBuilder the markupDocBuilder do use for output
-     * @param operation  the Swagger Operation
+     * @param operation        the Swagger Operation
      */
     private void buildOperationRef(MarkupDocBuilder markupDocBuilder, PathOperation operation) {
         buildOperationTitle(markupDocBuilder, crossReference(markupDocBuilder, operationDocumentResolverDefault.apply(operation), operation.getId(), operation.getTitle()), "ref-" + operation.getId());
@@ -234,8 +237,8 @@ public class PathsDocument extends MarkupComponent<PathsDocument.Parameters> {
     /**
      * Adds a operation title to the document.
      *
-     * @param title      the operation title
-     * @param anchor     optional anchor (null => auto-generate from title)
+     * @param title  the operation title
+     * @param anchor optional anchor (null => auto-generate from title)
      */
     private void buildOperationTitle(MarkupDocBuilder markupDocBuilder, String title, String anchor) {
         if (config.getPathsGroupedBy() == GroupBy.AS_IS) {
@@ -244,4 +247,12 @@ public class PathsDocument extends MarkupComponent<PathsDocument.Parameters> {
             markupDocBuilder.sectionTitleWithAnchorLevel3(title, anchor);
         }
     }
+
+    public static class Parameters {
+        private final Map<String, Path> paths;
+
+        public Parameters(Map<String, Path> paths) {
+            this.paths = paths;
+        }
+    }
 }

src/main/java/io/github/swagger2markup/internal/document/SecurityDocument.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -42,18 +42,10 @@ public class SecurityDocument extends MarkupComponent<SecurityDocument.Parameter
         this.securitySchemeDefinitionComponent = new SecuritySchemeDefinitionComponent(context);
     }
 
-    public static SecurityDocument.Parameters parameters(Map<String, SecuritySchemeDefinition> securitySchemeDefinitions){
+    public static SecurityDocument.Parameters parameters(Map<String, SecuritySchemeDefinition> securitySchemeDefinitions) {
         return new SecurityDocument.Parameters(securitySchemeDefinitions);
     }
 
-    public static class Parameters {
-        private final Map<String, SecuritySchemeDefinition> securitySchemeDefinitions;
-
-        public Parameters(Map<String, SecuritySchemeDefinition> securitySchemeDefinitions){
-            this.securitySchemeDefinitions = securitySchemeDefinitions;
-        }
-    }
-
     /**
      * Builds the security MarkupDocument.
      *
@@ -93,4 +85,12 @@ public class SecurityDocument extends MarkupComponent<SecurityDocument.Parameter
     private void applySecurityDocumentExtension(Context context) {
         extensionRegistry.getSecurityDocumentExtensions().forEach(extension -> extension.apply(context));
     }
+
+    public static class Parameters {
+        private final Map<String, SecuritySchemeDefinition> securitySchemeDefinitions;
+
+        public Parameters(Map<String, SecuritySchemeDefinition> securitySchemeDefinitions) {
+            this.securitySchemeDefinitions = securitySchemeDefinitions;
+        }
+    }
 }

src/main/java/io/github/swagger2markup/internal/resolver/DefinitionDocumentNameResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/io/github/swagger2markup/internal/resolver/DefinitionDocumentResolverDefault.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/io/github/swagger2markup/internal/resolver/DefinitionDocumentResolverFromDefinition.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/io/github/swagger2markup/internal/resolver/DocumentResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/io/github/swagger2markup/internal/resolver/OperationDocumentNameResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/io/github/swagger2markup/internal/resolver/OperationDocumentResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/io/github/swagger2markup/internal/resolver/OperationDocumentResolverDefault.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/io/github/swagger2markup/internal/resolver/SecurityDocumentResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/io/github/swagger2markup/internal/type/ArrayType.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/io/github/swagger2markup/internal/type/BasicType.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -38,7 +38,7 @@ public class BasicType extends Type {
 
     public BasicType(String type, String name, String format) {
         super(name);
-        Validate.notBlank(type);
+        Validate.notBlank(type, "Type of parameter '%s' must not be blank", name);
         this.type = type;
         this.format = format;
     }
@@ -46,7 +46,7 @@ public class BasicType extends Type {
     @Override
     public String displaySchema(MarkupDocBuilder docBuilder) {
         if (isNotBlank(this.format))
-            return String.format("%s(%s)", this.type, this.format);
+            return String.format("%s (%s)", this.type, this.format);
         else
             return this.type;
     }

src/main/java/io/github/swagger2markup/internal/type/EnumType.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/io/github/swagger2markup/internal/type/MapType.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,7 +25,7 @@ public class MapType extends Type {
 
     private Type keyType = new BasicType("string", null);
     private Type valueType;
-    
+
     public MapType(String name, Type valueType) {
         super(name);
         this.valueType = valueType;

src/main/java/io/github/swagger2markup/internal/type/ObjectType.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,7 +25,7 @@ import java.util.Map;
  * Complex object abstraction
  */
 public class ObjectType extends Type {
-    
+
     private Map<String, Property> properties;
     private ObjectTypePolymorphism polymorphism;
 
@@ -43,7 +43,7 @@ public class ObjectType extends Type {
     public String displaySchema(MarkupDocBuilder docBuilder) {
         return "object";
     }
-    
+
     public ObjectTypePolymorphism getPolymorphism() {
         return polymorphism;
     }

src/main/java/io/github/swagger2markup/internal/type/ObjectTypePolymorphism.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,12 +17,6 @@
 package io.github.swagger2markup.internal.type;
 
 public class ObjectTypePolymorphism {
-    
-    public enum Nature {
-        NONE,
-        COMPOSITION,
-        INHERITANCE
-    }
 
     public Nature nature = Nature.NONE;
     public String discriminator;
@@ -48,4 +42,10 @@ public class ObjectTypePolymorphism {
         this.discriminator = discriminator;
     }
 
+    public enum Nature {
+        NONE,
+        COMPOSITION,
+        INHERITANCE
+    }
+
 }

src/main/java/io/github/swagger2markup/internal/type/RefType.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/io/github/swagger2markup/internal/type/Type.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -35,14 +35,14 @@ public abstract class Type {
         this(name, name);
     }
 
-    public void setName(String name) {
-        this.name = name;
-    }
-
     public String getName() {
         return name;
     }
 
+    public void setName(String name) {
+        this.name = name;
+    }
+
     public String getUniqueName() {
         return uniqueName;
     }

src/main/java/io/github/swagger2markup/internal/utils/Example.java

@@ -0,0 +1,25 @@
+package io.github.swagger2markup.internal.utils;
+
+import io.github.swagger2markup.ExampleType;
+
+/**
+ * swagger2markup (c) Duco Hosting
+ * Created by cas on 02-Oct-17.
+ */
+public class Example {
+    private ExampleType type;
+    private Object example;
+
+    public Example(ExampleType type, Object example) {
+        this.type = type;
+        this.example = example;
+    }
+
+    public ExampleType getType() {
+        return type;
+    }
+
+    public Object getExample() {
+        return example;
+    }
+}

src/main/java/io/github/swagger2markup/internal/utils/ExamplesUtil.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -28,8 +28,6 @@ import io.swagger.models.properties.ArrayProperty;
 import io.swagger.models.properties.MapProperty;
 import io.swagger.models.properties.Property;
 import io.swagger.models.properties.RefProperty;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 
 import java.util.HashMap;
 import java.util.LinkedHashMap;
@@ -38,17 +36,15 @@ import java.util.Map;
 
 public class ExamplesUtil {
 
-    private static Logger logger = LoggerFactory.getLogger(ExamplesUtil.class);
-	
-	private static final Integer MAX_RECURSION_TO_DISPLAY = 2;
+    private static final Integer MAX_RECURSION_TO_DISPLAY = 2;
 
     /**
      * Generates a Map of response examples
      *
      * @param generateMissingExamples specifies the missing examples should be generated
-     * @param operation the Swagger Operation
-     * @param definitions the map of definitions
-     * @param markupDocBuilder the markup builder
+     * @param operation               the Swagger Operation
+     * @param definitions             the map of definitions
+     * @param markupDocBuilder        the markup builder
      * @return map containing response examples.
      */
     public static Map<String, Object> generateResponseExampleMap(boolean generateMissingExamples, PathOperation operation, Map<String, Model> definitions, DocumentResolver definitionDocumentResolver, MarkupDocBuilder markupDocBuilder) {
@@ -65,7 +61,10 @@ public class ExamplesUtil {
 
                         if (example == null && schema instanceof RefProperty) {
                             String simpleRef = ((RefProperty) schema).getSimpleRef();
-                            example = generateExampleForRefModel(generateMissingExamples, simpleRef, definitions, definitionDocumentResolver, markupDocBuilder, new HashMap< String, Integer >());
+                            example = generateExampleForRefModel(generateMissingExamples, simpleRef, definitions, definitionDocumentResolver, markupDocBuilder, new HashMap<>());
+                        }
+                        if (example == null && schema instanceof ArrayProperty && generateMissingExamples) {
+                            example = generateExampleForArrayProperty((ArrayProperty) schema, definitions, definitionDocumentResolver, markupDocBuilder, new HashMap<>());
                         }
                         if (example == null && generateMissingExamples) {
                             example = PropertyAdapter.generateExample(schema, markupDocBuilder);
@@ -85,9 +84,9 @@ public class ExamplesUtil {
      * Generates examples for request
      *
      * @param generateMissingExamples specifies the missing examples should be generated
-     * @param pathOperation the Swagger Operation
-     * @param definitions the map of definitions
-     * @param markupDocBuilder the markup builder
+     * @param pathOperation           the Swagger Operation
+     * @param definitions             the map of definitions
+     * @param markupDocBuilder        the markup builder
      * @return an Optional with the example content
      */
     public static Map<String, Object> generateRequestExampleMap(boolean generateMissingExamples, PathOperation pathOperation, Map<String, Model> definitions, DocumentResolver definitionDocumentResolver, MarkupDocBuilder markupDocBuilder) {
@@ -101,62 +100,14 @@ public class ExamplesUtil {
         for (Parameter parameter : parameters) {
             Object example = null;
             if (parameter instanceof BodyParameter) {
-                example = ((BodyParameter) parameter).getExamples();
-                if (example == null) {
-                    Model schema = ((BodyParameter) parameter).getSchema();
-                    if (schema instanceof RefModel) {
-                        String simpleRef = ((RefModel) schema).getSimpleRef();
-                        example = generateExampleForRefModel(generateMissingExamples, simpleRef, definitions, definitionDocumentResolver, markupDocBuilder, new HashMap< >());
-                    } else if (generateMissingExamples) {
-                        if (schema instanceof ComposedModel) {
-                            example = exampleMapForProperties(((ObjectType)ModelUtils.getType(schema, definitions, definitionDocumentResolver)).getProperties(), definitions, definitionDocumentResolver, markupDocBuilder, new HashMap<>());
-                        } else if (schema instanceof ArrayModel) {
-                            example = generateExampleForArrayModel((ArrayModel) schema, definitions, definitionDocumentResolver, markupDocBuilder, new HashMap<>());
-                        } else {
-                            example = schema.getExample();
-                            if (example == null) {
-                                example = exampleMapForProperties(schema.getProperties(), definitions, definitionDocumentResolver, markupDocBuilder, new HashMap<>());
-                            }
-                        }
-                    }
-                }
+                example = generateBodyParameterExample(parameter, generateMissingExamples, definitions, definitionDocumentResolver, markupDocBuilder);
             } else if (parameter instanceof AbstractSerializableParameter) {
                 if (generateMissingExamples) {
-                    Object abstractSerializableParameterExample;
-                    abstractSerializableParameterExample = ((AbstractSerializableParameter) parameter).getExample();
-                    if (abstractSerializableParameterExample == null) {
-                        Property item = ((AbstractSerializableParameter) parameter).getItems();
-                        if (item != null) {
-                            abstractSerializableParameterExample = item.getExample();
-                            if (abstractSerializableParameterExample == null) {
-                                abstractSerializableParameterExample = PropertyAdapter.generateExample(item, markupDocBuilder);
-                            }
-                        }
-                        if (abstractSerializableParameterExample == null) {
-                            abstractSerializableParameterExample = ParameterAdapter.generateExample((AbstractSerializableParameter)parameter);
-                        }
-                    }
-                    if (parameter instanceof PathParameter) {
-                        String pathExample = (String) examples.get("path");
-                        pathExample = pathExample.replace('{' + parameter.getName() + '}', String.valueOf(abstractSerializableParameterExample));
-                        example = pathExample;
-                    } else {
-                        example = abstractSerializableParameterExample;
-                    }
-                    if (parameter instanceof QueryParameter) {
-                        //noinspection unchecked
-                        @SuppressWarnings("unchecked")
-                        Map<String, Object> queryExampleMap = (Map<String, Object>) examples.get("query");
-                        if (queryExampleMap == null) {
-                            queryExampleMap = new LinkedHashMap<>();
-                        }
-                        queryExampleMap.put(parameter.getName(), abstractSerializableParameterExample);
-                        example = queryExampleMap;
-                    }
+                    example = generateAbstractSerializableParameterExample(parameter, examples, markupDocBuilder);
                 }
             } else if (parameter instanceof RefParameter) {
                 String simpleRef = ((RefParameter) parameter).getSimpleRef();
-                example = generateExampleForRefModel(generateMissingExamples, simpleRef, definitions, definitionDocumentResolver, markupDocBuilder, new HashMap< String, Integer >());
+                example = generateExampleForRefModel(generateMissingExamples, simpleRef, definitions, definitionDocumentResolver, markupDocBuilder, new HashMap<>());
             }
 
             if (example != null)
@@ -166,43 +117,120 @@ public class ExamplesUtil {
         return examples;
     }
 
+    /**
+     * Generates example for a body parameter
+     *
+     * @param parameter                  Body paramteter to generate example for
+     * @param generateMissingExamples    Should an example be generated if none is defined
+     * @param definitions                the map of definitions
+     * @param definitionDocumentResolver definitions document resolver
+     * @param markupDocBuilder           the markup builder
+     * @return Object containing example
+     */
+    private static Object generateBodyParameterExample(Parameter parameter, Boolean generateMissingExamples, Map<String, Model> definitions, DocumentResolver definitionDocumentResolver, MarkupDocBuilder markupDocBuilder) {
+        Object example = ((BodyParameter) parameter).getExamples();
+        if (example == null) {
+            Model schema = ((BodyParameter) parameter).getSchema();
+            if (schema instanceof RefModel) {
+                String simpleRef = ((RefModel) schema).getSimpleRef();
+                example = generateExampleForRefModel(generateMissingExamples, simpleRef, definitions, definitionDocumentResolver, markupDocBuilder, new HashMap<>());
+            } else if (generateMissingExamples) {
+                if (schema instanceof ComposedModel) {
+                    //FIXME: getProperties() may throw NullPointerException
+                    example = exampleMapForProperties(((ObjectType) ModelUtils.getType(schema, definitions, definitionDocumentResolver)).getProperties(), definitions, definitionDocumentResolver, markupDocBuilder, new HashMap<>());
+                } else if (schema instanceof ArrayModel) {
+                    example = generateExampleForArrayModel((ArrayModel) schema, definitions, definitionDocumentResolver, markupDocBuilder, new HashMap<>());
+                } else {
+                    example = schema.getExample();
+                    if (example == null) {
+                        example = exampleMapForProperties(schema.getProperties(), definitions, definitionDocumentResolver, markupDocBuilder, new HashMap<>());
+                    }
+                }
+            }
+        }
+
+        return example;
+    }
+
+    private static Object generateAbstractSerializableParameterExample(Parameter parameter, Map<String, Object> examples, MarkupDocBuilder markupDocBuilder) {
+        Object abstractSerializableParameterExample;
+        Object example;
+        abstractSerializableParameterExample = ((AbstractSerializableParameter) parameter).getExample();
+        if (abstractSerializableParameterExample == null) {
+            abstractSerializableParameterExample = parameter.getVendorExtensions().get("x-example");
+        }
+        if (abstractSerializableParameterExample == null) {
+            Property item = ((AbstractSerializableParameter) parameter).getItems();
+            if (item != null) {
+                abstractSerializableParameterExample = item.getExample();
+                if (abstractSerializableParameterExample == null) {
+                    abstractSerializableParameterExample = PropertyAdapter.generateExample(item, markupDocBuilder);
+                }
+            }
+            if (abstractSerializableParameterExample == null) {
+                abstractSerializableParameterExample = ParameterAdapter.generateExample((AbstractSerializableParameter) parameter);
+            }
+        }
+        if (parameter instanceof PathParameter) {
+            String pathExample = (String) examples.get("path");
+            pathExample = pathExample.replace('{' + parameter.getName() + '}', String.valueOf(abstractSerializableParameterExample));
+            example = pathExample;
+        } else {
+            example = abstractSerializableParameterExample;
+        }
+        if (parameter instanceof QueryParameter) {
+            //TODO: #264 query parameters seem to be collected here
+            //noinspection unchecked
+            @SuppressWarnings("unchecked")
+            Map<String, Object> queryExampleMap = (Map<String, Object>) examples.get("query");
+            if (queryExampleMap == null) {
+                queryExampleMap = new LinkedHashMap<>();
+            }
+            queryExampleMap.put(parameter.getName(), abstractSerializableParameterExample);
+            example = queryExampleMap;
+        }
+        return example;
+    }
+
     /**
      * Generates an example object from a simple reference
      *
      * @param generateMissingExamples specifies the missing examples should be generated
-     * @param simpleRef the simple reference string
-     * @param definitions the map of definitions
-     * @param markupDocBuilder the markup builder
-	 * @param refStack map to detect cyclic references
+     * @param simpleRef               the simple reference string
+     * @param definitions             the map of definitions
+     * @param markupDocBuilder        the markup builder
+     * @param refStack                map to detect cyclic references
      * @return returns an Object or Map of examples
      */
-    public static Object generateExampleForRefModel(boolean generateMissingExamples, String simpleRef, Map<String, Model> definitions, DocumentResolver definitionDocumentResolver, MarkupDocBuilder markupDocBuilder, Map< String, Integer > refStack) {
+    private static Object generateExampleForRefModel(boolean generateMissingExamples, String simpleRef, Map<String, Model> definitions, DocumentResolver definitionDocumentResolver, MarkupDocBuilder markupDocBuilder, Map<String, Integer> refStack) {
         Model model = definitions.get(simpleRef);
         Object example = null;
         if (model != null) {
             example = model.getExample();
             if (example == null && generateMissingExamples) {
-				if (!refStack.containsKey(simpleRef)) {
+                if (!refStack.containsKey(simpleRef)) {
                     refStack.put(simpleRef, 1);
                 } else {
                     refStack.put(simpleRef, refStack.get(simpleRef) + 1);
                 }
-				if (refStack.get(simpleRef) <= MAX_RECURSION_TO_DISPLAY) {
-					if (model instanceof ComposedModel) {
-                        example = exampleMapForProperties(((ObjectType)ModelUtils.getType(model, definitions, definitionDocumentResolver)).getProperties(), definitions, definitionDocumentResolver, markupDocBuilder, new HashMap<>());
-					} else {
-						example = exampleMapForProperties(model.getProperties(), definitions, definitionDocumentResolver, markupDocBuilder, refStack);
-					}
-				}else{
-					return "...";
-				}
-				refStack.put(simpleRef, refStack.get(simpleRef) - 1);
+                if (refStack.get(simpleRef) <= MAX_RECURSION_TO_DISPLAY) {
+                    if (model instanceof ComposedModel) {
+                        //FIXME: getProperties() may throw NullPointerException
+                        example = exampleMapForProperties(((ObjectType) ModelUtils.getType(model, definitions, definitionDocumentResolver)).getProperties(), definitions, definitionDocumentResolver, markupDocBuilder, new HashMap<>());
+                    } else {
+                        example = exampleMapForProperties(model.getProperties(), definitions, definitionDocumentResolver, markupDocBuilder, refStack);
+                    }
+                } else {
+                    return "...";
+                }
+                refStack.put(simpleRef, refStack.get(simpleRef) - 1);
             }
         }
         return example;
     }
 
     private static Map<String, Property> getPropertiesForComposedModel(ComposedModel model, Map<String, Model> definitions) {
+        //TODO: Unused method, make sure this is never used and then remove it.
         Map<String, Property> combinedProperties;
         if (model.getParent() instanceof RefModel) {
             Map<String, Property> parentProperties = definitions.get(((RefModel) model.getParent()).getSimpleRef()).getProperties();
@@ -231,14 +259,13 @@ public class ExamplesUtil {
      * Generates a map of examples from a map of properties. If defined examples are found, those are used. Otherwise,
      * examples are generated from the type.
      *
-     * @param properties the map of properties
-     * @param definitions the map of definitions
+     * @param properties       the map of properties
+     * @param definitions      the map of definitions
      * @param markupDocBuilder the markup builder
-	 * @param refStack map to detect cyclic references
-     *
+     * @param refStack         map to detect cyclic references
      * @return a Map of examples
      */
-    public static Map<String, Object> exampleMapForProperties(Map<String, Property> properties, Map<String, Model> definitions, DocumentResolver definitionDocumentResolver, MarkupDocBuilder markupDocBuilder, Map< String, Integer > refStack) {
+    private static Map<String, Object> exampleMapForProperties(Map<String, Property> properties, Map<String, Model> definitions, DocumentResolver definitionDocumentResolver, MarkupDocBuilder markupDocBuilder, Map<String, Integer> refStack) {
         Map<String, Object> exampleMap = new LinkedHashMap<>();
         if (properties != null) {
             for (Map.Entry<String, Property> property : properties.entrySet()) {
@@ -262,7 +289,7 @@ public class ExamplesUtil {
         return exampleMap;
     }
 
-    public static Object generateExampleForMapProperty(MapProperty property, MarkupDocBuilder markupDocBuilder) {
+    private static Object generateExampleForMapProperty(MapProperty property, MarkupDocBuilder markupDocBuilder) {
         if (property.getExample() != null) {
             return property.getExample();
         }
@@ -275,35 +302,46 @@ public class ExamplesUtil {
         return exampleMap;
     }
 
-    public static Object generateExampleForArrayModel(ArrayModel model, Map<String, Model> definitions, DocumentResolver definitionDocumentResolver, MarkupDocBuilder markupDocBuilder, Map< String, Integer > refStack) {
+    private static Object generateExampleForArrayModel(ArrayModel model, Map<String, Model> definitions, DocumentResolver definitionDocumentResolver, MarkupDocBuilder markupDocBuilder, Map<String, Integer> refStack) {
         if (model.getExample() != null) {
             return model.getExample();
         } else if (model.getProperties() != null) {
             return new Object[]{exampleMapForProperties(model.getProperties(), definitions, definitionDocumentResolver, markupDocBuilder, refStack)};
         } else {
             Property itemProperty = model.getItems();
-            if (itemProperty.getExample() != null) {
-                return new Object[]{itemProperty.getExample()};
-            } else if (itemProperty instanceof ArrayProperty) {
-                return new Object[]{generateExampleForArrayProperty((ArrayProperty) itemProperty, definitions, definitionDocumentResolver, markupDocBuilder, refStack)};
-            } else if (itemProperty instanceof RefProperty) {
-                return new Object[]{generateExampleForRefModel(true, ((RefProperty) itemProperty).getSimpleRef(), definitions, definitionDocumentResolver, markupDocBuilder, refStack)};
-            } else {
-                return new Object[]{PropertyAdapter.generateExample(itemProperty, markupDocBuilder)};
-            }
+            return getExample(itemProperty, definitions, definitionDocumentResolver, markupDocBuilder, refStack);
         }
     }
 
     /**
      * Generates examples from an ArrayProperty
      *
-     * @param value ArrayProperty
-     * @param definitions map of definitions
+     * @param value            ArrayProperty
+     * @param definitions      map of definitions
      * @param markupDocBuilder the markup builder
      * @return array of Object
      */
-    public static Object[] generateExampleForArrayProperty(ArrayProperty value, Map<String, Model> definitions, DocumentResolver definitionDocumentResolver, MarkupDocBuilder markupDocBuilder, Map< String, Integer > refStack) {
+    private static Object[] generateExampleForArrayProperty(ArrayProperty value, Map<String, Model> definitions, DocumentResolver definitionDocumentResolver, MarkupDocBuilder markupDocBuilder, Map<String, Integer> refStack) {
         Property property = value.getItems();
+        return getExample(property, definitions, definitionDocumentResolver, markupDocBuilder, refStack);
+    }
+
+    /**
+     * Get example from a property
+     *
+     * @param property                   Property
+     * @param definitions                map of definitions
+     * @param definitionDocumentResolver DocumentResolver
+     * @param markupDocBuilder           the markup builder
+     * @param refStack                   reference stack
+     * @return array of Object
+     */
+    private static Object[] getExample(
+            Property property,
+            Map<String, Model> definitions,
+            DocumentResolver definitionDocumentResolver,
+            MarkupDocBuilder markupDocBuilder,
+            Map<String, Integer> refStack) {
         if (property.getExample() != null) {
             return new Object[]{property.getExample()};
         } else if (property instanceof ArrayProperty) {
@@ -315,4 +353,7 @@ public class ExamplesUtil {
         }
     }
 
+    //TODO: Unused method, make sure this is never used and then remove it.
+    //FIXME: getProperties() may throw NullPointerException
+
 }

src/main/java/io/github/swagger2markup/internal/utils/InlineSchemaUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -20,7 +20,7 @@ import io.github.swagger2markup.internal.type.*;
 
 import java.util.List;
 
-import static org.apache.commons.collections4.MapUtils.*;
+import static org.apache.commons.collections4.MapUtils.isNotEmpty;
 
 public class InlineSchemaUtils {
     /**
@@ -29,9 +29,9 @@ public class InlineSchemaUtils {
      * The function is recursive and support collections (ArrayType and MapType).<br>
      * The function is transparent : {@code type} is returned as-is if type is not inlinable or if !config.isInlineSchemaEnabled().<br>
      *
-     * @param type type to inline
-     * @param name name of the created inline ObjectType
-     * @param uniqueName unique name of the created inline ObjectType
+     * @param type              type to inline
+     * @param name              name of the created inline ObjectType
+     * @param uniqueName        unique name of the created inline ObjectType
      * @param inlineDefinitions a non null collection of inline ObjectType
      * @return the type referencing the newly created inline ObjectType. Can be a RefType, an ArrayType or a MapType
      */
@@ -39,12 +39,12 @@ public class InlineSchemaUtils {
         if (type instanceof ObjectType) {
             return createInlineObjectType(type, name, uniqueName, inlineDefinitions);
         } else if (type instanceof ArrayType) {
-            ArrayType arrayType = (ArrayType)type;
+            ArrayType arrayType = (ArrayType) type;
             arrayType.setOfType(createInlineType(arrayType.getOfType(), name, uniqueName, inlineDefinitions));
 
             return arrayType;
         } else if (type instanceof MapType) {
-            MapType mapType = (MapType)type;
+            MapType mapType = (MapType) type;
             if (mapType.getValueType() instanceof ObjectType)
                 mapType.setValueType(createInlineType(mapType.getValueType(), name, uniqueName, inlineDefinitions));
 
@@ -56,7 +56,7 @@ public class InlineSchemaUtils {
 
     private static Type createInlineObjectType(Type type, String name, String uniqueName, List<ObjectType> inlineDefinitions) {
         if (type instanceof ObjectType) {
-            ObjectType objectType = (ObjectType)type;
+            ObjectType objectType = (ObjectType) type;
             if (isNotEmpty(objectType.getProperties())) {
                 if (objectType.getName() == null) {
                     objectType.setName(name);

src/main/java/io/github/swagger2markup/internal/utils/MapUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,18 +15,21 @@
  */
 package io.github.swagger2markup.internal.utils;
 
-import java.util.*;
+import java.util.Comparator;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.TreeMap;
 
 public class MapUtils {
 
     /**
      * Returns the the Map either ordered or as-is, if the comparator is null.
      *
-     * @param map the Map
+     * @param map        the Map
      * @param comparator the comparator to use.
      * @return the keySet of the Map
      */
-    public static <K, V> Map<K, V> toSortedMap(Map<K, V> map, Comparator<? super K> comparator){
+    public static <K, V> Map<K, V> toSortedMap(Map<K, V> map, Comparator<? super K> comparator) {
         Map<K, V> sortedMap;
         if (comparator == null)
             sortedMap = new LinkedHashMap<>();

src/main/java/io/github/swagger2markup/internal/utils/MarkupDocBuilderUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -27,32 +27,40 @@ public class MarkupDocBuilderUtils {
         return markupDocBuilder.copy(false);
     }
 
-    public static  String literalText(MarkupDocBuilder markupDocBuilder, String text) {
+    public static String literalText(MarkupDocBuilder markupDocBuilder, String text) {
         if (StringUtils.isBlank(text)) {
             return StringUtils.EMPTY;
         }
-        return copyMarkupDocBuilder(markupDocBuilder).literalText(text).toString();
-    }
-    public static  String boldText(MarkupDocBuilder markupDocBuilder, String text) {
-        if (StringUtils.isBlank(text)) {
-            return StringUtils.EMPTY;
-        }
-        return copyMarkupDocBuilder(markupDocBuilder).boldText(text).toString();
+        return copyMarkupDocBuilder(markupDocBuilder).literalText(escapeText(text)).toString();
     }
 
-    public static  String italicText(MarkupDocBuilder markupDocBuilder, String text) {
+    private static String escapeText(String text) {
+        if(text.startsWith("*")){
+            text = "\\" + text;
+        }
+        return text;
+    }
+
+    public static String boldText(MarkupDocBuilder markupDocBuilder, String text) {
         if (StringUtils.isBlank(text)) {
             return StringUtils.EMPTY;
         }
-        return copyMarkupDocBuilder(markupDocBuilder).italicText(text).toString();
+        return copyMarkupDocBuilder(markupDocBuilder).boldText(escapeText(text)).toString();
     }
 
-    public static  String crossReference(MarkupDocBuilder markupDocBuilder, String document, String anchor, String text) {
+    public static String italicText(MarkupDocBuilder markupDocBuilder, String text) {
+        if (StringUtils.isBlank(text)) {
+            return StringUtils.EMPTY;
+        }
+        return copyMarkupDocBuilder(markupDocBuilder).italicText(escapeText(text)).toString();
+    }
+
+    public static String crossReference(MarkupDocBuilder markupDocBuilder, String document, String anchor, String text) {
         return copyMarkupDocBuilder(markupDocBuilder)
                 .crossReference(document, anchor, text).toString();
     }
 
-    public static  String markupDescription(MarkupLanguage swaggerMarkupLanguage, MarkupDocBuilder markupDocBuilder, String markupText) {
+    public static String markupDescription(MarkupLanguage swaggerMarkupLanguage, MarkupDocBuilder markupDocBuilder, String markupText) {
         if (StringUtils.isBlank(markupText)) {
             return StringUtils.EMPTY;
         }

src/main/java/io/github/swagger2markup/internal/utils/ModelUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -33,6 +33,7 @@ public final class ModelUtils {
 
     /**
      * Recursively resolve referenced type if {@code type} is of type RefType
+     *
      * @param type type to resolve
      * @return referenced type
      */
@@ -68,7 +69,7 @@ public final class ModelUtils {
                 objectType.getPolymorphism().setDiscriminator(modelImpl.getDiscriminator());
 
                 return objectType;
-            } else if(isNotBlank(modelImpl.getFormat()))
+            } else if (isNotBlank(modelImpl.getFormat()))
                 return new BasicType(modelImpl.getType(), modelImpl.getTitle(), modelImpl.getFormat());
             else
                 return new BasicType(modelImpl.getType(), modelImpl.getTitle());
@@ -99,7 +100,7 @@ public final class ModelUtils {
                     }
                 }
             }
-            
+
             return new ObjectType(name, polymorphism, allProperties);
         } else if (model instanceof RefModel) {
             RefModel refModel = (RefModel) model;

src/main/java/io/github/swagger2markup/internal/utils/PathUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -28,7 +28,6 @@ public class PathUtils {
      * Returns the operations of a path as a map which preserves the insertion order.
      *
      * @param path the path
-     *
      * @return the operations of a path as a map
      */
     private static Map<HttpMethod, Operation> getOperationMap(Path path) {
@@ -62,10 +61,9 @@ public class PathUtils {
     /**
      * Converts the Swagger paths into a list of PathOperations.
      *
-     * @param paths the Swagger paths
-     * @param paths the basePath of all paths
+     * @param paths      the Swagger paths
+     * @param basePath   the basePath of all paths
      * @param comparator the comparator to use.
-     *
      * @return the path operations
      */
     public static List<PathOperation> toPathOperationsList(Map<String, Path> paths,
@@ -76,7 +74,7 @@ public class PathUtils {
         paths.forEach((relativePath, path) ->
                 pathOperations.addAll(toPathOperationsList(basePath + relativePath, path)));
         if (comparator != null) {
-            Collections.sort(pathOperations, comparator);
+            pathOperations.sort(comparator);
         }
         return pathOperations;
     }
@@ -84,9 +82,8 @@ public class PathUtils {
     /**
      * Converts a Swagger path into a PathOperation.
      *
-     * @param path the  path
+     * @param path      the  path
      * @param pathModel the Swagger Path model
-     *
      * @return the path operations
      */
     public static List<PathOperation> toPathOperationsList(String path, Path pathModel) {

src/main/java/io/github/swagger2markup/internal/utils/RegexUtils.java

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2016 Cas Eliëns
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.github.swagger2markup.internal.utils;
+
+import com.google.common.collect.LinkedHashMultimap;
+import com.google.common.collect.Multimap;
+import io.github.swagger2markup.model.PathOperation;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.Set;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+public class RegexUtils {
+    private static Logger logger = LoggerFactory.getLogger(TagUtils.class);
+
+
+    /**
+     * Alphabetically sort the list of groups
+     *
+     * @param groups List of available groups
+     * @return String[] of sorted groups
+     */
+    public static String[] toSortedArray(Set<String> groups) {
+        //TODO: sort in another way than just alphabetically
+        String[] sortedArray = groups.toArray(new String[groups.size()]);
+
+        Arrays.sort(sortedArray);
+
+        return sortedArray;
+    }
+
+    /**
+     * Groups the operations by regex group. The key of the Multimap is the group name.
+     * The value of the Multimap is a PathOperation
+     *
+     * @param allOperations all operations
+     * @param headerPattern regex pattern used for determining headers
+     * @return Operations grouped by regex
+     */
+    public static Multimap<String, PathOperation> groupOperationsByRegex(List<PathOperation> allOperations, Pattern headerPattern) {
+
+        Multimap<String, PathOperation> operationsGroupedByRegex = LinkedHashMultimap.create();
+
+
+        for (PathOperation operation : allOperations) {
+            String path = operation.getPath();
+            Matcher m = headerPattern.matcher(path);
+
+            if (m.matches() && m.group(1) != null) {
+                if (logger.isDebugEnabled()) {
+                    logger.debug("Added path operation '{}' to header '{}'", operation, m.group(1));
+                }
+                operationsGroupedByRegex.put(m.group(1), operation);
+            } else {
+                if(logger.isWarnEnabled()) {
+                    logger.warn("Operation '{}' does not match regex '{}' and will not be included in output", operation, headerPattern.toString());
+                }
+            }
+        }
+
+        return operationsGroupedByRegex;
+    }
+}

src/main/java/io/github/swagger2markup/internal/utils/TagUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -28,15 +28,14 @@ import java.util.*;
 
 public class TagUtils {
 
-    private static Logger LOG = LoggerFactory.getLogger(TagUtils.class);
+    private static Logger logger = LoggerFactory.getLogger(TagUtils.class);
 
     /**
      * Converts the global Tag list into a Map where the tag name is the key and the Tag the value.
      * Either ordered or as-is, if the comparator is null.
      *
-     * @param tags the List of tags
+     * @param tags       the List of tags
      * @param comparator the comparator to use.
-     *
      * @return the Map of tags. Either ordered or as-is, if the comparator is null.
      */
     public static Map<String, Tag> toSortedMap(List<Tag> tags, Comparator<String> comparator) {
@@ -53,16 +52,16 @@ public class TagUtils {
      * Groups the operations by tag. The key of the Multimap is the tag name.
      * The value of the Multimap is a PathOperation
      *
-     * @param allOperations all operations
+     * @param allOperations     all operations
      * @param operationOrdering comparator for operations, for a given tag
      * @return Operations grouped by Tag
      */
     public static Multimap<String, PathOperation> groupOperationsByTag(List<PathOperation> allOperations, Comparator<PathOperation> operationOrdering) {
 
         Multimap<String, PathOperation> operationsGroupedByTag;
-        if (operationOrdering == null){
+        if (operationOrdering == null) {
             operationsGroupedByTag = LinkedHashMultimap.create();
-        }else {
+        } else {
             operationsGroupedByTag = MultimapBuilder.linkedHashKeys().treeSetValues(operationOrdering).build();
         }
         for (PathOperation operation : allOperations) {
@@ -70,8 +69,8 @@ public class TagUtils {
 
             Validate.notEmpty(tags, "Can't GroupBy.TAGS. Operation '%s' has no tags", operation);
             for (String tag : tags) {
-                if (LOG.isInfoEnabled()) {
-                    LOG.info("Added path operation '{}' to tag '{}'", operation, tag);
+                if (logger.isDebugEnabled()) {
+                    logger.debug("Added path operation '{}' to tag '{}'", operation, tag);
                 }
                 operationsGroupedByTag.put(tag, operation);
             }

src/main/java/io/github/swagger2markup/model/PathOperation.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -43,6 +43,7 @@ public class PathOperation {
 
     /**
      * Returns the display title for an operation
+     *
      * @return the operation title
      */
     public String getTitle() {

src/main/java/io/github/swagger2markup/spi/AbstractExtension.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/io/github/swagger2markup/spi/ContentContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/io/github/swagger2markup/spi/DefinitionsDocumentExtension.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,16 +16,51 @@
 
 package io.github.swagger2markup.spi;
 
-import com.google.common.base.Optional;
 import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
 import io.swagger.models.Model;
 import org.apache.commons.lang3.Validate;
 
+import java.util.Optional;
+
 /**
  * DefinitionsDocumentExtension extension point can be used to extend the definitions document content.
  */
 public abstract class DefinitionsDocumentExtension extends AbstractExtension {
 
+
+    public abstract void apply(Context context);
+
+    /**
+     * Returns title level offset from 1 to apply to content
+     *
+     * @param context context
+     * @return title level offset
+     */
+    protected int levelOffset(Context context) throws RuntimeException {
+        //TODO: Unused method, make sure this is never used and then remove it.
+        int levelOffset;
+        switch (context.position) {
+            case DOCUMENT_BEFORE:
+            case DOCUMENT_AFTER:
+                levelOffset = 0;
+                break;
+            case DOCUMENT_BEGIN:
+            case DOCUMENT_END:
+            case DEFINITION_BEFORE:
+            case DEFINITION_AFTER:
+                levelOffset = 1;
+                break;
+            case DEFINITION_BEGIN:
+            case DEFINITION_END:
+                levelOffset = 2;
+                break;
+            default:
+                throw new RuntimeException(String.format("Unknown position '%s'", context.position));
+        }
+
+        return levelOffset;
+    }
+
     public enum Position {
         DOCUMENT_BEFORE,
         DOCUMENT_BEGIN,
@@ -50,7 +85,7 @@ public abstract class DefinitionsDocumentExtension extends AbstractExtension {
         private Model model;
 
         /**
-         * @param position the current position
+         * @param position   the current position
          * @param docBuilder the MarkupDocBuilder
          */
         public Context(Position position, MarkupDocBuilder docBuilder) {
@@ -60,10 +95,10 @@ public abstract class DefinitionsDocumentExtension extends AbstractExtension {
         }
 
         /**
-         * @param position the current position
-         * @param docBuilder the MarkupDocBuilder
+         * @param position       the current position
+         * @param docBuilder     the MarkupDocBuilder
          * @param definitionName the name of the current definition
-         * @param model the current Model of the definition
+         * @param model          the current Model of the definition
          */
         public Context(Position position, MarkupDocBuilder docBuilder, String definitionName, Model model) {
             super(docBuilder);
@@ -80,45 +115,11 @@ public abstract class DefinitionsDocumentExtension extends AbstractExtension {
         }
 
         public Optional<String> getDefinitionName() {
-            return Optional.fromNullable(definitionName);
+            return Optional.ofNullable(definitionName);
         }
 
         public Optional<Model> getModel() {
-            return Optional.fromNullable(model);
+            return Optional.ofNullable(model);
         }
     }
-
-    public DefinitionsDocumentExtension() {
-    }
-
-    public abstract void apply(Context context);
-
-    /**
-     * Returns title level offset from 1 to apply to content
-     * @param context context
-     * @return title level offset
-     */
-    protected int levelOffset(Context context) {
-        int levelOffset;
-        switch (context.position) {
-            case DOCUMENT_BEFORE:
-            case DOCUMENT_AFTER:
-                levelOffset = 0;
-                break;
-            case DOCUMENT_BEGIN:
-            case DOCUMENT_END:
-            case DEFINITION_BEFORE:
-            case DEFINITION_AFTER:
-                levelOffset = 1;
-                break;
-            case DEFINITION_BEGIN:
-            case DEFINITION_END:
-                levelOffset = 2;
-                break;
-            default:
-                throw new RuntimeException(String.format("Unknown position '%s'", context.position));
-        }
-
-        return levelOffset;
-    }
 }

src/main/java/io/github/swagger2markup/spi/Extension.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/io/github/swagger2markup/spi/MarkupComponent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,18 +25,16 @@ import javaslang.Function2;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-public abstract class MarkupComponent <T> implements Function2<MarkupDocBuilder, T, MarkupDocBuilder> {
-
-    protected Logger logger = LoggerFactory.getLogger(getClass());
+public abstract class MarkupComponent<T> implements Function2<MarkupDocBuilder, T, MarkupDocBuilder> {
 
     protected static final String COLON = " : ";
-
+    protected Logger logger = LoggerFactory.getLogger(getClass());
     protected Swagger2MarkupConverter.Context context;
     protected Labels labels;
     protected Swagger2MarkupConfig config;
     protected Swagger2MarkupExtensionRegistry extensionRegistry;
 
-    public MarkupComponent(Swagger2MarkupConverter.Context context){
+    public MarkupComponent(Swagger2MarkupConverter.Context context) {
         this.context = context;
         this.config = context.getConfig();
         this.extensionRegistry = context.getExtensionRegistry();

src/main/java/io/github/swagger2markup/spi/OverviewDocumentExtension.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,41 +23,17 @@ import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
  */
 public abstract class OverviewDocumentExtension extends AbstractExtension {
 
-    public enum Position {
-        DOCUMENT_BEFORE,
-        DOCUMENT_AFTER,
-        DOCUMENT_BEGIN,
-        DOCUMENT_END
-    }
-
-    public static class Context extends ContentContext {
-        private Position position;
-
-        /**
-         * @param position the current position
-         * @param docBuilder the MarkupDocBuilder
-         */
-        public Context(Position position, MarkupDocBuilder docBuilder) {
-            super(docBuilder);
-            this.position = position;
-        }
-
-        public Position getPosition() {
-            return position;
-        }
-    }
-
-    public OverviewDocumentExtension() {
-    }
 
     public abstract void apply(Context context);
 
     /**
      * Returns title level offset from 1 to apply to content
+     *
      * @param context context
      * @return title level offset
      */
     protected int levelOffset(Context context) {
+        //TODO: Unused method, make sure this is never used and then remove it.
         int levelOffset;
         switch (context.position) {
             case DOCUMENT_BEFORE:
@@ -75,4 +51,28 @@ public abstract class OverviewDocumentExtension extends AbstractExtension {
         return levelOffset;
     }
 
+    public enum Position {
+        DOCUMENT_BEFORE,
+        DOCUMENT_AFTER,
+        DOCUMENT_BEGIN,
+        DOCUMENT_END
+    }
+
+    public static class Context extends ContentContext {
+        private Position position;
+
+        /**
+         * @param position   the current position
+         * @param docBuilder the MarkupDocBuilder
+         */
+        public Context(Position position, MarkupDocBuilder docBuilder) {
+            super(docBuilder);
+            this.position = position;
+        }
+
+        public Position getPosition() {
+            return position;
+        }
+    }
+
 }

src/main/java/io/github/swagger2markup/spi/PathsDocumentExtension.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -27,6 +27,68 @@ import org.apache.commons.lang3.Validate;
  */
 public abstract class PathsDocumentExtension extends AbstractExtension {
 
+
+    public abstract void apply(Context context);
+
+    /**
+     * Returns title level offset from 1 to apply to content
+     *
+     * @param context context
+     * @return title level offset
+     */
+    protected int levelOffset(Context context) {
+        //TODO: Unused method, make sure this is never used and then remove it.
+        int levelOffset;
+        switch (context.position) {
+            case DOCUMENT_BEFORE:
+            case DOCUMENT_AFTER:
+                levelOffset = 0;
+                break;
+            case DOCUMENT_BEGIN:
+            case DOCUMENT_END:
+            case OPERATION_BEFORE:
+            case OPERATION_AFTER:
+                levelOffset = 1;
+                break;
+            case OPERATION_BEGIN:
+            case OPERATION_END:
+                levelOffset = increaseLevelOffset(2);
+                break;
+            case OPERATION_DESCRIPTION_BEFORE:
+            case OPERATION_DESCRIPTION_AFTER:
+            case OPERATION_PARAMETERS_BEFORE:
+            case OPERATION_PARAMETERS_AFTER:
+            case OPERATION_RESPONSES_BEFORE:
+            case OPERATION_RESPONSES_AFTER:
+            case OPERATION_SECURITY_BEFORE:
+            case OPERATION_SECURITY_AFTER:
+                levelOffset = increaseLevelOffset(2);
+                break;
+            case OPERATION_DESCRIPTION_BEGIN:
+            case OPERATION_DESCRIPTION_END:
+            case OPERATION_PARAMETERS_BEGIN:
+            case OPERATION_PARAMETERS_END:
+            case OPERATION_RESPONSES_BEGIN:
+            case OPERATION_RESPONSES_END:
+            case OPERATION_SECURITY_BEGIN:
+            case OPERATION_SECURITY_END:
+                levelOffset = 3;
+                break;
+            default:
+                throw new RuntimeException(String.format("Unknown position '%s'", context.position));
+        }
+        return levelOffset;
+    }
+
+    private int increaseLevelOffset(int levelOffset) {
+        //TODO: This method always receives levelOffset=2. Perhaps the parameter could be removed
+        if (globalContext.getConfig().getPathsGroupedBy() == GroupBy.TAGS) {
+            return ++levelOffset;
+        } else {
+            return levelOffset;
+        }
+    }
+
     public enum Position {
         DOCUMENT_BEFORE,
         DOCUMENT_BEGIN,
@@ -75,6 +137,7 @@ public abstract class PathsDocumentExtension extends AbstractExtension {
 
         /**
          * Context for all other positions
+         *
          * @param position   the current position
          * @param docBuilder the MarkupDocBuilder
          * @param operation  the current path operation
@@ -95,66 +158,4 @@ public abstract class PathsDocumentExtension extends AbstractExtension {
             return Optional.fromNullable(operation);
         }
     }
-
-    public PathsDocumentExtension() {
-    }
-
-    public abstract void apply(Context context);
-
-    /**
-     * Returns title level offset from 1 to apply to content
-     *
-     * @param context context
-     * @return title level offset
-     */
-    protected int levelOffset(Context context) {
-        int levelOffset;
-        switch (context.position) {
-            case DOCUMENT_BEFORE:
-            case DOCUMENT_AFTER:
-                levelOffset = 0;
-                break;
-            case DOCUMENT_BEGIN:
-            case DOCUMENT_END:
-            case OPERATION_BEFORE:
-            case OPERATION_AFTER:
-                levelOffset = 1;
-                break;
-            case OPERATION_BEGIN:
-            case OPERATION_END:
-                levelOffset = increaseLevelOffset(2);
-                break;
-            case OPERATION_DESCRIPTION_BEFORE:
-            case OPERATION_DESCRIPTION_AFTER:
-            case OPERATION_PARAMETERS_BEFORE:
-            case OPERATION_PARAMETERS_AFTER:
-            case OPERATION_RESPONSES_BEFORE:
-            case OPERATION_RESPONSES_AFTER:
-            case OPERATION_SECURITY_BEFORE:
-            case OPERATION_SECURITY_AFTER:
-                levelOffset = increaseLevelOffset(2);
-                break;
-            case OPERATION_DESCRIPTION_BEGIN:
-            case OPERATION_DESCRIPTION_END:
-            case OPERATION_PARAMETERS_BEGIN:
-            case OPERATION_PARAMETERS_END:
-            case OPERATION_RESPONSES_BEGIN:
-            case OPERATION_RESPONSES_END:
-            case OPERATION_SECURITY_BEGIN:
-            case OPERATION_SECURITY_END:
-                levelOffset = 3;
-                break;
-            default:
-                throw new RuntimeException(String.format("Unknown position '%s'", context.position));
-        }
-        return levelOffset;
-    }
-
-    private int increaseLevelOffset(int levelOffset) {
-        if (globalContext.getConfig().getPathsGroupedBy() == GroupBy.TAGS) {
-            return ++levelOffset;
-        }else {
-            return levelOffset;
-        }
-    }
 }

src/main/java/io/github/swagger2markup/spi/SecurityDocumentExtension.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -26,6 +26,40 @@ import org.apache.commons.lang3.Validate;
  */
 public abstract class SecurityDocumentExtension extends AbstractExtension {
 
+
+    public abstract void apply(Context context);
+
+    /**
+     * Returns title level offset from 1 to apply to content
+     *
+     * @param context context
+     * @return title level offset
+     */
+    protected int levelOffset(Context context) {
+        //TODO: Unused method, make sure this is never used and then remove it.
+        int levelOffset;
+        switch (context.position) {
+            case DOCUMENT_BEFORE:
+            case DOCUMENT_AFTER:
+                levelOffset = 0;
+                break;
+            case DOCUMENT_BEGIN:
+            case DOCUMENT_END:
+            case SECURITY_SCHEME_BEFORE:
+            case SECURITY_SCHEME_AFTER:
+                levelOffset = 1;
+                break;
+            case SECURITY_SCHEME_BEGIN:
+            case SECURITY_SCHEME_END:
+                levelOffset = 2;
+                break;
+            default:
+                throw new RuntimeException(String.format("Unknown position '%s'", context.position));
+        }
+
+        return levelOffset;
+    }
+
     public enum Position {
         DOCUMENT_BEFORE,
         DOCUMENT_BEGIN,
@@ -49,7 +83,7 @@ public abstract class SecurityDocumentExtension extends AbstractExtension {
         private SecuritySchemeDefinition securityScheme;
 
         /**
-         * @param position the current position
+         * @param position   the current position
          * @param docBuilder the MarkupDocBuilder
          */
         public Context(Position position, MarkupDocBuilder docBuilder) {
@@ -59,10 +93,10 @@ public abstract class SecurityDocumentExtension extends AbstractExtension {
         }
 
         /**
-         * @param position the current position
-         * @param docBuilder the MarkupDocBuilder
+         * @param position           the current position
+         * @param docBuilder         the MarkupDocBuilder
          * @param securitySchemeName the name of the current securityScheme
-         * @param securityScheme the current security scheme securityScheme
+         * @param securityScheme     the current security scheme securityScheme
          */
         public Context(Position position, MarkupDocBuilder docBuilder, String securitySchemeName, SecuritySchemeDefinition securityScheme) {
             super(docBuilder);
@@ -87,38 +121,4 @@ public abstract class SecurityDocumentExtension extends AbstractExtension {
         }
     }
 
-    public SecurityDocumentExtension() {
-    }
-
-    public abstract void apply(Context context);
-
-    /**
-     * Returns title level offset from 1 to apply to content
-     * @param context context
-     * @return title level offset
-     */
-    protected int levelOffset(Context context) {
-        int levelOffset;
-        switch (context.position) {
-            case DOCUMENT_BEFORE:
-            case DOCUMENT_AFTER:
-                levelOffset = 0;
-                break;
-            case DOCUMENT_BEGIN:
-            case DOCUMENT_END:
-            case SECURITY_SCHEME_BEFORE:
-            case SECURITY_SCHEME_AFTER:
-                levelOffset = 1;
-                break;
-            case SECURITY_SCHEME_BEGIN:
-            case SECURITY_SCHEME_END:
-                levelOffset = 2;
-                break;
-            default:
-                throw new RuntimeException(String.format("Unknown position '%s'", context.position));
-        }
-
-        return levelOffset;
-    }
-
 }

src/main/java/io/github/swagger2markup/spi/SwaggerModelExtension.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,9 +23,6 @@ import io.swagger.models.Swagger;
  */
 public abstract class SwaggerModelExtension extends AbstractExtension {
 
-    public SwaggerModelExtension() {
-    }
-
     public abstract void apply(Swagger swagger);
 
 }

src/main/java/io/github/swagger2markup/utils/IOUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/io/github/swagger2markup/utils/URIUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,6 +23,7 @@ import java.nio.file.Paths;
 public class URIUtils {
     /**
      * Return URI parent
+     *
      * @param uri source URI
      * @return URI parent
      */
@@ -36,7 +37,7 @@ public class URIUtils {
      * @param uri the source URI
      * @return the converted URI
      */
-    public static URI convertUriWithoutSchemeToFileScheme(URI uri){
+    public static URI convertUriWithoutSchemeToFileScheme(URI uri) {
         if (uri.getScheme() == null) {
             return Paths.get(uri.getPath()).toUri();
         }
@@ -49,10 +50,10 @@ public class URIUtils {
      * @param input String representation of a URI or a Path.
      * @return the URI
      */
-    public static URI create(String input){
-        if(isFile(input) || isURL(input)){
+    public static URI create(String input) {
+        if (isFile(input) || isURL(input)) {
             return URI.create(input);
-        }else{
+        } else {
             return Paths.get(input).toUri();
         }
     }

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

@@ -24,3 +24,5 @@ swagger2markup.definitionOrderBy=NATURAL
 swagger2markup.parameterOrderBy=NATURAL
 swagger2markup.propertyOrderBy=NATURAL
 swagger2markup.responseOrderBy=NATURAL
+swagger2markup.listDelimiterEnabled=false
+swagger2markup.listDelimiter=,

src/main/resources/io/github/swagger2markup/lang/labels_de.properties

@@ -1,7 +1,5 @@
 definitions=Definitionen
-
 default_column=Standard
-
 # validators
 minlength_column=Mindestl\u00E4nge
 maxlength_column=Maximale L\u00E4nge
@@ -11,7 +9,6 @@ minvalue_column=Mindestwert
 minvalue_exclusive_column=Mindestwert (exklusiv)
 maxvalue_column=Maximalwert
 maxvalue_exclusive_column=Maximalwert (exklusiv)
-
 example_column=Beispiel
 flags.column=Flags
 flags.required=verpflichtend
@@ -33,7 +30,7 @@ contact_information=Kontaktinformationen
 contact_name=Kontakt
 contact_email=Kontakt E-Mail
 license_information=Lizenzinformationen
-license=Linzenz
+license=Lizenz
 license_url=Lizenz-URL
 terms_of_service=Nutzungsbedingungen
 uri_scheme=URI Schema
@@ -48,6 +45,7 @@ security_authorizationUrl=Token URL
 security_tokenUrl=Token URL
 paths=Pfade
 resources=Ressourcen
+operations=Betrieb
 security=Sicherheit
 body_parameter=Body Parameter
 parameters=Parameter
@@ -66,3 +64,6 @@ polymorphism.column=Polymorphism
 polymorphism.discriminator=Discriminator
 polymorphism.nature.INHERITANCE=Inheritance
 polymorphism.nature.COMPOSITION=Composition
+external_docs=Externe Doku
+external_docs_desc=Beschreibung
+external_docs_url=URL

src/main/resources/io/github/swagger2markup/lang/labels_en.properties

@@ -1,7 +1,5 @@
 definitions=Definitions
-
 default_column=Default
-
 # validators
 minlength_column=Minimum length
 maxlength_column=Maximal length
@@ -11,7 +9,6 @@ minvalue_column=Minimum value
 minvalue_exclusive_column=Minimum value (exclusive)
 maxvalue_column=Maximum value
 maxvalue_exclusive_column=Maximum value (exclusive)
-
 example_column=Example
 flags.column=Flags
 flags.required=Required
@@ -26,7 +23,6 @@ scopes_column=Scopes
 produces=Produces
 consumes=Consumes
 tags=Tags
-
 overview=Overview
 current_version=Version information
 version=Version
@@ -47,9 +43,9 @@ security_in=In
 security_flow=Flow
 security_authorizationUrl=Token URL
 security_tokenUrl=Token URL
-
 paths=Paths
 resources=Resources
+operations=Operations
 security=Security
 parameters=Parameters
 body_parameter=Body parameter
@@ -61,11 +57,13 @@ example_response=Example HTTP response
 type_column=Type
 http_code_column=HTTP Code
 parameter=Parameter
-
 unknown=Unknown
 no_content=No Content
 operation.deprecated=This operation is deprecated.
 polymorphism.column=Polymorphism
 polymorphism.discriminator=Discriminator
 polymorphism.nature.INHERITANCE=Inheritance
-polymorphism.nature.COMPOSITION=Composition
+polymorphism.nature.COMPOSITION=Composition
+external_docs=External Docs
+external_docs_desc=Description
+external_docs_url=URL

src/main/resources/io/github/swagger2markup/lang/labels_es.properties

@@ -1,7 +1,5 @@
 definitions=Definiciones
-
 default_column=Valor por defecto
-
 # validators
 minlength_column=Longitud m\u00EDnima
 maxlength_column=Longitud m\u00E1xima
@@ -11,7 +9,6 @@ minvalue_column=Valor m\u00EDnimo
 minvalue_exclusive_column=Valor m\u00EDnimo (exclusivo)
 maxvalue_column=Valor m\u00E1ximo
 maxvalue_exclusive_column=Valor m\u00E1ximo (exclusivo)
-
 example_column=Ejemplo
 flags.column=Flags
 flags.required=Obligatorio
@@ -26,7 +23,6 @@ scopes_column=Scopes
 produces=Produce
 consumes=Consume
 tags=Etiquetas
-
 overview=Resumen
 current_version=Informaci\u00F3n de versi\u00F3n
 version=Versi\u00F3n
@@ -47,9 +43,9 @@ security_in=En
 security_flow=Flujo
 security_authorizationUrl=URL de autorizaci\u00F3n
 security_tokenUrl=URL del token
-
 paths=Rutas
 resources=Recursos
+operations=Operaciones
 security=Seguridad
 parameters=Par\u00E1metros
 body_parameter=Par\u00E1metro de cuerpo
@@ -61,11 +57,13 @@ example_response=Ejemplo de respuesta HTTP
 type_column=Tipo
 http_code_column=C\u00F3digo HTTP
 parameter=Par\u00E1metro
-
 unknown=Desconocido
 no_content=Sin contenido
 operation.deprecated=Operaci\u00F3n obsoleta
 polymorphism.column=Polimorfismo
 polymorphism.discriminator=Discriminador
 polymorphism.nature.INHERITANCE=Herencia
-polymorphism.nature.COMPOSITION=Composici\u00F3n
+polymorphism.nature.COMPOSITION=Composici\u00F3n
+external_docs=External Docs
+external_docs_desc=Description
+external_docs_url=URL

src/main/resources/io/github/swagger2markup/lang/labels_fr.properties

@@ -1,7 +1,5 @@
 definitions=D\u00E9finitions
-
 default_column=D\u00E9faut
-
 # validators
 minlength_column=Longueur minimale
 maxlength_column=Longueur maximale
@@ -11,7 +9,6 @@ minvalue_column=Valeur minimale
 minvalue_exclusive_column=Valeur minimale (exclusif)
 maxvalue_column=Valeur maximale
 maxvalue_exclusive_column=Valeur maximale (exclusif)
-
 example_column=Exemple
 flags.column=Modificateurs
 flags.required=Requis
@@ -26,7 +23,6 @@ scopes_column=P\u00E9rim\u00E8tre
 produces=Produit
 consumes=Consomme
 tags=Tags
-
 overview=Vue g\u00E9n\u00E9rale
 current_version=Information de version
 version=Version
@@ -47,9 +43,9 @@ security_in=Position
 security_flow=Flux
 security_authorizationUrl=URL d'autorisation
 security_tokenUrl=URL de jeton
-
 paths=Op\u00E9rations
 resources=Ressources
+operations=Op\u00E9rations
 security=S\u00E9curit\u00E9
 parameters=Param\u00E8tres
 body_parameter=Contenu
@@ -61,11 +57,13 @@ example_response=Exemple de r\u00E9ponse HTTP
 type_column=Type
 http_code_column=Code HTTP
 parameter=Param\u00E8tre
-
 unknown=Inconnu
 no_content=Pas de contenu
 operation.deprecated=Cette op\u00E9ration est obsol\u00E8te.
 polymorphism.column=Polymorphisme
 polymorphism.discriminator=Discriminateur
 polymorphism.nature.INHERITANCE=H\u00E9ritage
-polymorphism.nature.COMPOSITION=Composition
+polymorphism.nature.COMPOSITION=Composition
+external_docs=External Docs
+external_docs_desc=Description
+external_docs_url=URL

src/main/resources/io/github/swagger2markup/lang/labels_ja.properties

@@ -1,7 +1,5 @@
 definitions=\u30e2\u30c7\u30eb\u5b9a\u7fa9
-
 default_column=\u30c7\u30d5\u30a9\u30eb\u30c8
-
 # validators
 minlength_column=\u6700\u4f4e\u9577
 maxlength_column=\u6700\u5927\u9577
@@ -11,7 +9,6 @@ minvalue_column=\u6700\u5c0f\u5024
 minvalue_exclusive_column=\u6700\u5c0f\u5024(\u5883\u754c\u5024\u9664\u5916)
 maxvalue_column=\u6700\u5927\u5024
 maxvalue_exclusive_column=\u6700\u5927\u5024(\u5883\u754c\u5024\u9664\u5916)
-
 example_column=\u4f8b
 flags.column=\u30d5\u30e9\u30b0
 flags.required=\u5fc5\u9808
@@ -26,7 +23,6 @@ scopes_column=\u30b9\u30b3\u30fc\u30d7
 produces=\u51fa\u529b\u5f62\u5f0f
 consumes=\u5165\u529b\u5f62\u5f0f
 tags=\u30bf\u30b0
-
 overview=\u6982\u8981
 current_version=\u30d0\u30fc\u30b8\u30e7\u30f3\u60c5\u5831
 version=\u30d0\u30fc\u30b8\u30e7\u30f3
@@ -47,9 +43,9 @@ security_in=\u6307\u5b9a\u7b87\u6240
 security_flow=\u30d5\u30ed\u30fc
 security_authorizationUrl=\u30c8\u30fc\u30af\u30f3 URL
 security_tokenUrl=\u30c8\u30fc\u30af\u30f3 URL
-
 paths=\u30d1\u30b9
 resources=\u30ea\u30bd\u30fc\u30b9
+operations=\u30AA\u30DA\u30EC\u30FC\u30B7\u30E7\u30F3
 security=\u30bb\u30ad\u30e5\u30ea\u30c6\u30a3
 parameters=\u30d1\u30e9\u30e1\u30fc\u30bf
 body_parameter=\u30dc\u30c7\u30a3\u30d1\u30e9\u30e1\u30fc\u30bf
@@ -61,7 +57,6 @@ example_response=HTTP \u30ec\u30b9\u30dd\u30f3\u30b9\u4f8b
 type_column=\u30bf\u30a4\u30d7
 http_code_column=HTTP \u30b3\u30fc\u30c9
 parameter=\u30d1\u30e9\u30e1\u30fc\u30bf
-
 unknown=\u4e0d\u660e
 no_content=No Content
 operation.deprecated=\u3053\u306e\u64cd\u4f5c\u306f\u975e\u63a8\u5968\u3067\u3059\u3002
@@ -69,3 +64,6 @@ polymorphism.column=\u30dd\u30ea\u30e2\u30fc\u30d5\u30a3\u30ba\u30e0
 polymorphism.discriminator=Discriminator
 polymorphism.nature.INHERITANCE=\u7d99\u627f
 polymorphism.nature.COMPOSITION=\u5305\u542b
+external_docs=External Docs
+external_docs_desc=Description
+external_docs_url=URL

src/main/resources/io/github/swagger2markup/lang/labels_pt_BR.properties

@@ -1,7 +1,5 @@
 definitions=Definitions
-
 default_column=Padr\u00e3o
-
 # validators
 minlength_column=Tamanho m\u00ednimo
 maxlength_column=Tamanho M\u00e1ximo
@@ -11,7 +9,6 @@ minvalue_column=Valor m\u00ednimo
 minvalue_exclusive_column=Valor m\u00ednimo (exclusivo)
 maxvalue_column=Valor m\u00e1ximo
 maxvalue_exclusive_column=Valor m\u00e1ximo (exclusivo)
-
 example_column=Exemplo
 flags.column=Flags
 flags.required=Obrigat\u00f3rio
@@ -26,7 +23,6 @@ scopes_column=Escopos
 produces=Produz
 consumes=Consome
 tags=Tags
-
 overview=Vis\u00e3o Geral
 current_version=Informa\u00e7\u00f5es da Vers\u00e3o
 version=Vers\u00e3o
@@ -47,9 +43,9 @@ security_in=No
 security_flow=Fluxo
 security_authorizationUrl=URL do Token
 security_tokenUrl=URL do Token
-
 paths=Paths
 resources=Recursos
+operations=Opera\u00E7\u00F5es
 security=Seguran\u00e7a
 parameters=Par\u00e2metros
 body_parameter=Par\u00e2metro de corpo
@@ -61,11 +57,13 @@ example_response=Exemplo de resposta HTTP
 type_column=Tipo
 http_code_column=C\u00f3digo de status HTTP
 parameter=Par\u00e2metro
-
 unknown=Desconhecido
 no_content=Nenhum conte\u00fado
 operation.deprecated=Essa opera\u00e7\u00e3o est\u00e1 obsoleta.
 polymorphism.column=Polimorfismo
 polymorphism.discriminator=Discriminador
 polymorphism.nature.INHERITANCE=Heran\u00e7a
-polymorphism.nature.COMPOSITION=Composi\u00e7\u00e3o
+polymorphism.nature.COMPOSITION=Composi\u00e7\u00e3o
+external_docs=External Docs
+external_docs_desc=Description
+external_docs_url=URL

src/main/resources/io/github/swagger2markup/lang/labels_ru.properties

@@ -1,39 +1,35 @@
 definitions=\u041E\u043F\u0440\u0435\u0434\u0435\u043B\u0435\u043D\u0438\u044F
-
 default_column=\u041F\u043E \u0443\u043C\u043E\u043B\u0447\u0430\u043D\u0438\u044E
-
 # validators
-minlength_column=Minimum length
-maxlength_column=Maximal length
-length_column=Length
-pattern_column=Pattern
-minvalue_column=Minimum value
-minvalue_exclusive_column=Minimum value (exclusive)
-maxvalue_column=Maximum value
-maxvalue_exclusive_column=Maximum value (exclusive)
-
-flags.column=Flags
+minlength_column=\u041C\u0438\u043D\u0438\u043C\u0430\u043B\u044C\u043D\u0430\u044F \u0434\u043B\u0438\u043D\u0430
+maxlength_column=\u041C\u0430\u043A\u0441\u0438\u043C\u0430\u043B\u044C\u043D\u0430\u044F \u0434\u043B\u0438\u043D\u0430
+length_column=\u0414\u043B\u0438\u043D\u0430
+pattern_column=\u0428\u0430\u0431\u043B\u043E\u043D
+minvalue_column=\u041C\u0438\u043D\u0438\u043C\u0430\u043B\u044C\u043D\u043E\u0435 \u0437\u043D\u0430\u0447\u0435\u043D\u0438\u0435
+minvalue_exclusive_column=\u041C\u0438\u043D\u0438\u043C\u0430\u043B\u044C\u043D\u043E\u0435 \u0437\u043D\u0430\u0447\u0435\u043D\u0438\u0435 (\u0438\u0441\u043A\u043B\u044E\u0447\u0435\u043D\u0438\u0435)
+maxvalue_column=\u041C\u0430\u043A\u0441\u0438\u043C\u0430\u043B\u044C\u043D\u043E\u0435 \u0437\u043D\u0430\u0447\u0435\u043D\u0438\u0435
+maxvalue_exclusive_column=\u041C\u0430\u043A\u0441\u0438\u043C\u0430\u043B\u044C\u043D\u043E\u0435 \u0437\u043D\u0430\u0447\u0435\u043D\u0438\u0435 (\u0438\u0441\u043A\u043B\u044E\u0447\u0435\u043D\u0438\u0435)
+flags.column=\u0424\u043B\u0430\u0433\u0438
 flags.required=\u041E\u0431\u044F\u0437\u0430\u0442\u0435\u043B\u044C\u043D\u043E
-flags.optional=Optional
-flags.read_only=Read-only
-flags.read_write=Read-write
+flags.optional=\u041D\u0435\u043E\u0431\u044F\u0437\u0430\u0442\u0435\u043B\u044C\u043D\u043E
+flags.read_only=\u0422\u043E\u043B\u044C\u043A\u043E \u0434\u043B\u044F \u0447\u0442\u0435\u043D\u0438\u044F
+flags.read_write=\u0427\u0442\u0435\u043D\u0438\u0435 \u0438 \u0437\u0430\u043F\u0438\u0441\u044C
 example_column=\u041F\u0440\u0438\u043C\u0435\u0440
 schema_column=\u0421\u0445\u0435\u043C\u0430
 name_column=\u0418\u043C\u044F
 description_column=\u041E\u043F\u0438\u0441\u0430\u043D\u0438\u0435
-headers_column=Headers
+headers_column=\u0417\u0430\u0433\u043E\u043B\u043E\u0432\u043A\u0438
 scopes_column=\u041E\u0431\u043B\u0430\u0441\u0442\u0438 \u043F\u0440\u0438\u043C\u0435\u043D\u0435\u043D\u0438\u044F
 produces=\u0412\u043E\u0437\u0432\u0440\u0430\u0449\u0430\u0435\u0442
 consumes=\u041F\u0440\u0438\u043D\u0438\u043C\u0430\u0435\u0442
-tags=\u0422\u044D\u0433\u0438
-
+tags=\u0422\u0435\u0433\u0438
 overview=\u041E\u0431\u0437\u043E\u0440
 current_version=\u0418\u043D\u0444\u043E\u0440\u043C\u0430\u0446\u0438\u044F \u043E \u0432\u0435\u0440\u0441\u0438\u0438
 version=\u0412\u0435\u0440\u0441\u0438\u044F
 contact_information=\u041A\u043E\u043D\u0442\u0430\u043A\u0442\u043D\u0430\u044F \u0438\u043D\u0444\u043E\u0440\u043C\u0430\u0446\u0438\u044F
 contact_name=\u041A\u043E\u043D\u0442\u0430\u043A\u0442
-contact_email=Email \u043A\u043E\u043D\u0442\u0430\u043A\u0442\u0430
-license_information=\u0418\u043D\u0444\u043E\u0440\u043C\u0430\u0446\u0438\u044F \u043E \u043B\u0438\u0446\u0435\u043D\u0446\u0438\u0438
+contact_email=E-mail \u043A\u043E\u043D\u0442\u0430\u043A\u0442\u0430
+license_information=\u0418\u043D\u0444\u043E\u0440\u043C\u0430\u0446\u0438\u044F \u043E \u043B\u0438\u0446\u0435\u043D\u0437\u0438\u0438
 license=\u041B\u0438\u0446\u0435\u043D\u0437\u0438\u044F
 license_url=URL \u043B\u0438\u0446\u0435\u043D\u0437\u0438\u0438
 terms_of_service=\u0423\u0441\u043B\u043E\u0432\u0438\u044F \u0438\u0441\u043F\u043E\u043B\u044C\u0437\u043E\u0432\u0430\u043D\u0438\u044F
@@ -47,9 +43,9 @@ security_in=\u0421\u043E\u0434\u0435\u0440\u0436\u0438\u0442\u0441\u044F \u0432
 security_flow=\u041F\u043E\u0442\u043E\u043A
 security_authorizationUrl=URL \u0430\u0432\u0442\u043E\u0440\u0438\u0437\u0430\u0446\u0438\u0438
 security_tokenUrl=URL \u0442\u043E\u043A\u0435\u043D\u0430
-
 paths=\u041F\u0443\u0442\u0438
 resources=\u0420\u0435\u0441\u0443\u0440\u0441\u044B
+operations=\u041E\u043F\u0435\u0440\u0430\u0446\u0438\u0438
 security=\u0411\u0435\u0437\u043E\u043F\u0430\u0441\u043D\u043E\u0441\u0442\u044C
 response=\u041E\u0442\u0432\u0435\u0442
 request=\u0417\u0430\u043F\u0440\u043E\u0441
@@ -57,15 +53,17 @@ parameters=\u041F\u0430\u0440\u0430\u043C\u0435\u0442\u0440\u044B
 body_parameter=\u041F\u0430\u0440\u0430\u043C\u0435\u0442\u0440 \u0442\u0435\u043B\u0430 \u0437\u0430\u043F\u0440\u043E\u0441\u0430
 responses=\u041E\u0442\u0432\u0435\u0442\u044B
 example_request=\u041F\u0440\u0438\u043C\u0435\u0440 HTTP \u0437\u0430\u043F\u0440\u043E\u0441\u0430
-example_response=\u041F\u0440\u0438\u043C\u0435\u0440 HTTP \u0437\u0430\u043F\u0440\u043E\u0441\u0430
+example_response=\u041F\u0440\u0438\u043C\u0435\u0440 HTTP \u043E\u0442\u0432\u0435\u0442\u0430
 type_column=\u0422\u0438\u043F
 http_code_column=HTTP \u043A\u043E\u0434
 parameter=\u041F\u0430\u0440\u0430\u043C\u0435\u0442\u0440
-
-unknown=Unknown
+unknown=\u041D\u0435\u0438\u0437\u0432\u0435\u0441\u0442\u043D\u044B\u0439
 no_content=\u0411\u0435\u0437 \u0441\u043E\u0434\u0435\u0440\u0436\u0438\u043C\u043E\u0433\u043E
 operation.deprecated=\u042D\u0442\u0430 \u043E\u043F\u0435\u0440\u0430\u0446\u0438\u044F \u0443\u0441\u0442\u0430\u0440\u0435\u043B\u0430.
-polymorphism.column=Polymorphism
-polymorphism.discriminator=Discriminator
-polymorphism.nature.INHERITANCE=Inheritance
-polymorphism.nature.COMPOSITION=Composition
+polymorphism.column=\u041F\u043E\u043B\u0438\u043C\u043E\u0440\u0444\u0438\u0437\u043C
+polymorphism.discriminator=\u0414\u0438\u0441\u043A\u0440\u0438\u043C\u0438\u043D\u0430\u0442\u043E\u0440
+polymorphism.nature.INHERITANCE=\u041D\u0430\u0441\u043B\u0435\u0434\u043E\u0432\u0430\u043D\u0438\u0435
+polymorphism.nature.COMPOSITION=\u0421\u0442\u0440\u0443\u043A\u0442\u0443\u0440\u0430
+external_docs=External Docs
+external_docs_desc=Description
+external_docs_url=URL

src/main/resources/io/github/swagger2markup/lang/labels_tr.properties

@@ -1,7 +1,5 @@
 definitions=Tan\u0131mlar
-
 default_column=Varsay\u0131lan
-
 # validators
 minlength_column=Minimum length
 maxlength_column=Maximal length
@@ -11,7 +9,6 @@ minvalue_column=Minimum value
 minvalue_exclusive_column=Minimum value (exclusive)
 maxvalue_column=Maximum value
 maxvalue_exclusive_column=Maximum value (exclusive)
-
 example_column=\u00D6rnek
 flags.column=Bayraklar
 flags.required=Gerekli
@@ -26,7 +23,6 @@ scopes_column=Kapsamlar
 produces=\u00DCretilenler
 consumes=Kullan\u0131lanlar
 tags=Etiketler
-
 overview=Genel Bak\u0131\u015F
 current_version=Versiyon bilgisi
 version=Versiyon
@@ -47,9 +43,9 @@ security_in=Yer
 security_flow=Ak\u0131\u015F
 security_authorizationUrl=Yetkilendirme adresi
 security_tokenUrl=Token adresi
-
 paths=Dizinler
 resources=Kaynaklar
+operations=Operasyonlar
 security=G\u00FCvenlik
 parameters=Parametreler
 body_parameter=G\u00F6vde parametresi
@@ -61,11 +57,13 @@ example_response=\u00D6rnek HTTP cevab\u0131
 type_column=Tip
 http_code_column=HTTP Kodu
 parameter=Parametre
-
 unknown=Bilinmeyen
 no_content=\u0130\u00E7erik yok
 operation.deprecated=Bu i\u015Flem \u00F6nerilmemektedir.
 polymorphism.column=\u00C7okbi\u00E7imlilik
 polymorphism.discriminator=Ayr\u0131\u015Ft\u0131r\u0131c\u0131
 polymorphism.nature.INHERITANCE=Kal\u0131t\u0131m
-polymorphism.nature.COMPOSITION=Birle\u015Ftirme
+polymorphism.nature.COMPOSITION=Birle\u015Ftirme
+external_docs=External Docs
+external_docs_desc=Description
+external_docs_url=URL

src/main/resources/io/github/swagger2markup/lang/labels_zh.properties

@@ -1,7 +1,5 @@
 definitions=\u5b9a\u4e49
-
-default_column=\u9ed8\u8ba4\u5217
-
+default_column=\u9ed8\u8ba4\u503c
 # validators
 minlength_column=\u6700\u5c0f\u957f\u5ea6
 maxlength_column=\u6700\u5927\u957f\u5ea6
@@ -11,14 +9,13 @@ minvalue_column=\u6700\u5c0f\u503c
 minvalue_exclusive_column=\u6700\u5c0f\u503c(\u4e0d\u5305\u62ec)
 maxvalue_column=\u6700\u5927\u503c
 maxvalue_exclusive_column=\u6700\u5927\u503c(\u4e0d\u5305\u62ec)
-
-example_column=\u4f8b\u5b50
+example_column=\u6837\u4f8b
 flags.column=\u6807\u5fd7
 flags.required=\u5fc5\u586b
 flags.optional=\u53ef\u9009
 flags.read_only=\u53ea\u8bfb
 flags.read_write=\u8bfb\u5199
-schema_column=\u67b6\u6784
+schema_column=\u7c7b\u578b
 name_column=\u540d\u79f0
 description_column=\u8bf4\u660e
 headers_column=\u5934
@@ -26,8 +23,7 @@ scopes_column=\u4f5c\u7528\u57df
 produces=\u751f\u6210
 consumes=\u6d88\u8017
 tags=\u6807\u7b7e
-
-overview=\u6982\u89c2
+overview=\u6982\u89c8
 current_version=\u7248\u672c\u4fe1\u606f
 version=\u7248\u672c
 contact_information=\u8054\u7cfb\u65b9\u5f0f
@@ -47,9 +43,9 @@ security_in=\u5728
 security_flow=\u6d41
 security_authorizationUrl=\u6388\u6743\u7f51\u5740
 security_tokenUrl=\u4ee4\u724c\u7f51\u5740
-
 paths=\u8def\u5f84
 resources=\u8d44\u6e90
+operations=\u64CD\u4F5C
 security=\u5b89\u5168
 parameters=\u53c2\u6570
 body_parameter=Body\u53c2\u6570
@@ -61,7 +57,6 @@ example_response=HTTP\u54cd\u5e94\u793a\u4f8b
 type_column=\u7c7b\u578b
 http_code_column=HTTP\u4ee3\u7801
 parameter=\u53c2\u6570
-
 unknown=\u672a\u77e5
 no_content=\u65e0\u5185\u5bb9
 operation.deprecated=\u8be5\u64cd\u4f5c\u5df2\u5f03\u7528
@@ -69,3 +64,6 @@ polymorphism.column=\u591a\u6001\u6027
 polymorphism.discriminator=\u9274\u522b
 polymorphism.nature.INHERITANCE=\u7ee7\u627f
 polymorphism.nature.COMPOSITION=\u6210\u5206
+external_docs=External Docs
+external_docs_desc=Description
+external_docs_url=URL

src/test/java/io/github/swagger2markup/AsciidocConverterTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,8 +21,6 @@ import org.apache.commons.io.FileUtils;
 import org.apache.commons.io.IOUtils;
 import org.junit.Before;
 import org.junit.Test;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 
 import java.io.IOException;
 import java.net.URISyntaxException;
@@ -39,12 +37,11 @@ import static org.assertj.core.api.BDDAssertions.assertThat;
 
 public class AsciidocConverterTest {
 
-    private static final Logger LOG = LoggerFactory.getLogger(AsciidocConverterTest.class);
     private static final String[] EXPECTED_FILES = new String[]{"definitions.adoc", "overview.adoc", "paths.adoc", "security.adoc"};
     private List<String> expectedFiles;
-    
+
     @Before
-    public void setUp(){
+    public void setUp() {
         expectedFiles = new ArrayList<>(asList(EXPECTED_FILES));
     }
 
@@ -165,6 +162,32 @@ public class AsciidocConverterTest {
         DiffUtils.assertThatAllFilesAreEqual(expectedFilesDirectory, outputDirectory, "testOrderingNatural.html");
     }
 
+    @Test
+    public void testOrderByRegex() throws IOException, URISyntaxException {
+        //Given
+        Path file = Paths.get(AsciidocConverterTest.class.getResource("/yaml/swagger_ordering_regex.yaml").toURI());
+        Path outputDirectory = Paths.get("build/test/asciidoc/ordering_regex");
+        FileUtils.deleteQuietly(outputDirectory.toFile());
+
+        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
+                .withTagOrdering(OrderBy.NATURAL)
+                .withParameterOrdering(OrderBy.NATURAL)
+                .withOperationOrdering(OrderBy.NATURAL)
+                .withPathsGroupedBy(GroupBy.REGEX)
+                .withHeaderRegex("\\/(\\w+)(\\/|\\w)*$")
+                .build();
+
+        //When
+        Swagger2MarkupConverter.from(file).withConfig(config).build()
+                .toFolder(outputDirectory);
+
+        //Then
+        String[] files = outputDirectory.toFile().list();
+        assertThat(files).hasSize(4).containsAll(expectedFiles);
+
+        Path expectedFilesDirectory = Paths.get(AsciidocConverterTest.class.getResource("/expected/asciidoc/ordering_regex").toURI());
+        DiffUtils.assertThatAllFilesAreEqual(expectedFilesDirectory, outputDirectory, "testOrderingRegex.html");
+    }
 
     @Test
     public void testMarkupRenderingInInstagram() throws IOException, URISyntaxException {
@@ -200,7 +223,7 @@ public class AsciidocConverterTest {
         Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                 .withInterDocumentCrossReferences()
                 .build();
-        
+
         Swagger2MarkupConverter.from(file).withConfig(config).build()
                 .toFolder(outputDirectory);
 
@@ -264,7 +287,6 @@ public class AsciidocConverterTest {
 
         //When
         Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
-                .withoutInlineSchema()
                 .build();
 
         Swagger2MarkupConverter.from(swaggerJsonString)
@@ -288,7 +310,6 @@ public class AsciidocConverterTest {
 
         //When
         Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
-                .withoutInlineSchema()
                 .withGeneratedExamples()
                 .build();
 
@@ -303,8 +324,8 @@ public class AsciidocConverterTest {
         Path expectedFilesDirectory = Paths.get(AsciidocConverterTest.class.getResource("/expected/asciidoc/generated_examples").toURI());
         DiffUtils.assertThatAllFilesAreEqual(expectedFilesDirectory, outputDirectory, "testWithGeneratedExamples.html");
     }
-	
-	@Test
+
+    @Test
     public void testWithGeneratedRecursiveExamples() throws IOException, URISyntaxException {
         // Given
         String swaggerJsonString = IOUtils.toString(getClass().getResourceAsStream("/json/swagger_recursion.json"));
@@ -597,7 +618,7 @@ public class AsciidocConverterTest {
         Path expectedFilesDirectory = Paths.get(AsciidocConverterTest.class.getResource("/expected/asciidoc/enums").toURI());
         DiffUtils.assertThatAllFilesAreEqual(expectedFilesDirectory, outputDirectory, "testWithEnums.html");
     }
-    
+
 
     @Test
     public void testWithValidators() throws IOException, URISyntaxException {
@@ -724,11 +745,11 @@ public class AsciidocConverterTest {
 
         //When
         Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
-            .build();
+                .build();
         Swagger2MarkupConverter.from(file)
-            .withConfig(config)
-            .build()
-            .toFolder(outputDirectory);
+                .withConfig(config)
+                .build()
+                .toFolder(outputDirectory);
 
         //Then
         String[] files = outputDirectory.toFile().list();
@@ -737,4 +758,53 @@ public class AsciidocConverterTest {
         Path expectedFilesDirectory = Paths.get(AsciidocConverterTest.class.getResource("/expected/asciidoc/format").toURI());
         DiffUtils.assertThatAllFilesAreEqual(expectedFilesDirectory, outputDirectory, "testWithFormat.html");
     }
+
+    @Test
+    public void testWithPageBreaks() throws IOException, URISyntaxException {
+        //Given
+        String swaggerJsonString = IOUtils.toString(getClass().getResourceAsStream("/json/swagger_examples.json"));
+        Path outputDirectory = Paths.get("build/test/asciidoc/page_breaks");
+        FileUtils.deleteQuietly(outputDirectory.toFile());
+
+        //When
+        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
+                .withPageBreaks(new ArrayList<>(asList(PageBreakLocations.BEFORE_OPERATION, PageBreakLocations.BEFORE_OPERATION_EXAMPLE_REQUEST)))
+                .build();
+
+        Swagger2MarkupConverter.from(swaggerJsonString)
+                .withConfig(config)
+                .build()
+                .toFolder(outputDirectory);
+
+        //Then
+        String[] files = outputDirectory.toFile().list();
+        assertThat(files).hasSize(4).containsAll(expectedFiles);
+        Path expectedFilesDirectory = Paths.get(AsciidocConverterTest.class.getResource("/expected/asciidoc/page_breaks").toURI());
+        DiffUtils.assertThatAllFilesAreEqual(expectedFilesDirectory, outputDirectory, "testWithPageBreaks.html");
+    }
+
+    @Test
+    public void testWithQueryParameters() throws IOException, URISyntaxException {
+        //Given
+        Path file = Paths.get(AsciidocConverterTest.class.getResource("/yaml/swagger_query_params.yaml").toURI());
+        Path outputDirectory = Paths.get("build/test/asciidoc/query_params");
+        FileUtils.deleteQuietly(outputDirectory.toFile());
+
+        //When
+        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
+                .withGeneratedExamples()
+                .build();
+
+        Swagger2MarkupConverter.from(file)
+                .withConfig(config)
+                .build()
+                .toFolder(outputDirectory);
+
+        //Then
+        String[] files = outputDirectory.toFile().list();
+        assertThat(files).hasSize(4).containsAll(expectedFiles);
+
+        Path expectedFilesDirectory = Paths.get(AsciidocConverterTest.class.getResource("/expected/asciidoc/query_params").toURI());
+        DiffUtils.assertThatAllFilesAreEqual(expectedFilesDirectory, outputDirectory, "textWithQueryParameters.html");
+    }
 }

src/test/java/io/github/swagger2markup/DocumentationTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -80,7 +80,7 @@ public class DocumentationTest {
         // end::convertIntoString[]
     }
 
-    public void swagger2MarkupConfigBuilder(){
+    public void swagger2MarkupConfigBuilder() {
         Path localSwaggerFile = Paths.get("/path/to/swagger.yaml");
 
         // tag::swagger2MarkupConfigBuilder[]
@@ -160,4 +160,4 @@ public class DocumentationTest {
                 .build();
         // end::swagger2MarkupConfigFromCommonsConfiguration[]
     }
-}
+}

src/test/java/io/github/swagger2markup/GeneralConverterTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -37,7 +37,7 @@ public class GeneralConverterTest {
     private List<String> expectedFiles;
 
     @Before
-    public void setUp(){
+    public void setUp() {
         expectedFiles = new ArrayList<>(asList(EXPECTED_FILES));
     }
 
@@ -115,5 +115,5 @@ public class GeneralConverterTest {
         String[] files = outputDirectory.toFile().list();
         assertThat(files).hasSize(4).containsAll(expectedFiles);
     }
-    
+
 }

src/test/java/io/github/swagger2markup/MarkdownConverterTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -48,144 +48,6 @@ public class MarkdownConverterTest {
     private static final String[] EXPECTED_FILES = new String[]{"definitions.md", "overview.md", "paths.md", "security.md"};
     private List<String> expectedFiles;
 
-    @Before
-    public void setUp(){
-        expectedFiles = new ArrayList<>(asList(EXPECTED_FILES));
-    }
-
-
-    @Test
-    public void testToFolder() throws IOException, URISyntaxException {
-        //Given
-        Path file = Paths.get(MarkdownConverterTest.class.getResource("/yaml/swagger_petstore.yaml").toURI());
-        Path outputDirectory = Paths.get("build/test/markdown/to_folder");
-        FileUtils.deleteQuietly(outputDirectory.toFile());
-
-        //When
-        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
-                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
-                .build();
-        Swagger2MarkupConverter.from(file)
-                .withConfig(config)
-                .build()
-                .toFolder(outputDirectory);
-
-        //Then
-        String[] files = outputDirectory.toFile().list();
-        assertThat(files).hasSize(4).containsAll(expectedFiles);
-
-        Path expectedFilesDirectory = Paths.get(AsciidocConverterTest.class.getResource("/expected/markdown/to_folder").toURI());
-        DiffUtils.assertThatAllFilesAreEqual(expectedFilesDirectory, outputDirectory, "testToFolder.html");
-    }
-
-    @Test
-    public void testWithInterDocumentCrossReferences() throws IOException, URISyntaxException {
-        //Given
-        Path file = Paths.get(AsciidocConverterTest.class.getResource("/yaml/swagger_petstore.yaml").toURI());
-        Path outputDirectory = Paths.get("build/test/markdown/idxref");
-        FileUtils.deleteQuietly(outputDirectory.toFile());
-
-        //When
-        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
-                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
-                .withInterDocumentCrossReferences()
-                .build();
-
-        Swagger2MarkupConverter.from(file).withConfig(config).build()
-                .toFolder(outputDirectory);
-
-        //Then
-        String[] files = outputDirectory.toFile().list();
-        assertThat(files).hasSize(4).containsAll(expectedFiles);
-
-        Path expectedFilesDirectory = Paths.get(AsciidocConverterTest.class.getResource("/expected/markdown/idxref").toURI());
-        DiffUtils.assertThatAllFilesAreEqual(expectedFilesDirectory, outputDirectory, "testWithInterDocumentCrossReferences.html");
-    }
-    
-    @Test
-    public void testWithSeparatedDefinitions() throws IOException, URISyntaxException {
-        //Given
-        Path file = Paths.get(MarkdownConverterTest.class.getResource("/yaml/swagger_petstore.yaml").toURI());
-        Path outputDirectory = Paths.get("build/test/markdown/generated");
-        FileUtils.deleteQuietly(outputDirectory.toFile());
-
-        //When
-        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
-                .withSeparatedDefinitions()
-                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
-                .build();
-        Swagger2MarkupConverter.from(file)
-                .withConfig(config)
-                .build()
-                .toFolder(outputDirectory);
-
-        //Then
-        String[] files = outputDirectory.toFile().list();
-        expectedFiles.add("definitions");
-        assertThat(files).hasSize(5).containsAll(expectedFiles);
-
-        Path definitionsDirectory = outputDirectory.resolve("definitions");
-        String[] definitions = definitionsDirectory.toFile().list();
-        assertThat(definitions).hasSize(5).containsAll(
-                asList("Category.md", "Order.md", "Pet.md", "Tag.md", "User.md"));
-    }
-
-    @Test
-    public void testWithResponseHeaders() throws IOException, URISyntaxException {
-        //Given
-        Path file = Paths.get(AsciidocConverterTest.class.getResource("/yaml/swagger_response_headers.yaml").toURI());
-        Path outputDirectory = Paths.get("build/test/markdown/response_headers");
-        FileUtils.deleteQuietly(outputDirectory.toFile());
-
-        //When
-        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
-                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
-                .build();
-        Swagger2MarkupConverter.from(file)
-                .withConfig(config)
-                .build()
-                .toFolder(outputDirectory);
-
-        //Then
-        String[] files = outputDirectory.toFile().list();
-        assertThat(files).hasSize(4).containsAll(expectedFiles);
-
-        Path expectedFilesDirectory = Paths.get(AsciidocConverterTest.class.getResource("/expected/markdown/response_headers").toURI());
-        DiffUtils.assertThatAllFilesAreEqual(expectedFilesDirectory, outputDirectory, "testWithResponseHeaders.html");
-    }
-    
-    @Test
-    public void testHandlesComposition() throws IOException, URISyntaxException {
-        //Given
-        Path file = Paths.get(MarkdownConverterTest.class.getResource("/yaml/swagger_petstore.yaml").toURI());
-        Path outputDirectory = Paths.get("build/test/markdown/generated");
-        FileUtils.deleteQuietly(outputDirectory.toFile());
-
-        //When
-        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
-                .withSeparatedDefinitions()
-                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
-                .build();
-        Swagger2MarkupConverter.from(file)
-                .withConfig(config)
-                .build()
-                .toFolder(outputDirectory);
-
-        // Then
-        String[] files = outputDirectory.toFile().list();
-        expectedFiles.add("definitions");
-        assertThat(files).hasSize(5).containsAll(expectedFiles);
-        Path definitionsDirectory = outputDirectory.resolve("definitions");
-        verifyMarkdownContainsFieldsInTables(
-                definitionsDirectory.resolve("User.md").toFile(),
-                ImmutableMap.<String, Set<String>>builder()
-                        .put("User", ImmutableSet.of("id", "username", "firstName",
-                                "lastName", "email", "password", "phone", "userStatus"))
-                        .build()
-        );
-
-    }
-
     /**
      * Given a markdown document to search, this checks to see if the specified tables
      * have all of the expected fields listed.
@@ -197,6 +59,7 @@ public class MarkdownConverterTest {
      * @throws IOException if the markdown document could not be read
      */
     private static void verifyMarkdownContainsFieldsInTables(File doc, Map<String, Set<String>> fieldsByTable) throws IOException {
+        //TODO: This method is too complex, split it up in smaller methods to increase readability
         final List<String> lines = Files.readAllLines(doc.toPath(), Charset.defaultCharset());
         final Map<String, Set<String>> fieldsLeftByTable = Maps.newHashMap();
         for (Map.Entry<String, Set<String>> entry : fieldsByTable.entrySet()) {
@@ -250,4 +113,141 @@ public class MarkdownConverterTest {
                 ? line.replace("###", "").trim()
                 : null;
     }
+
+    @Before
+    public void setUp() {
+        expectedFiles = new ArrayList<>(asList(EXPECTED_FILES));
+    }
+
+    @Test
+    public void testToFolder() throws IOException, URISyntaxException {
+        //Given
+        Path file = Paths.get(MarkdownConverterTest.class.getResource("/yaml/swagger_petstore.yaml").toURI());
+        Path outputDirectory = Paths.get("build/test/markdown/to_folder");
+        FileUtils.deleteQuietly(outputDirectory.toFile());
+
+        //When
+        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
+                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
+                .build();
+        Swagger2MarkupConverter.from(file)
+                .withConfig(config)
+                .build()
+                .toFolder(outputDirectory);
+
+        //Then
+        String[] files = outputDirectory.toFile().list();
+        assertThat(files).hasSize(4).containsAll(expectedFiles);
+
+        Path expectedFilesDirectory = Paths.get(AsciidocConverterTest.class.getResource("/expected/markdown/to_folder").toURI());
+        DiffUtils.assertThatAllFilesAreEqual(expectedFilesDirectory, outputDirectory, "testToFolder.html");
+    }
+
+    @Test
+    public void testWithInterDocumentCrossReferences() throws IOException, URISyntaxException {
+        //Given
+        Path file = Paths.get(AsciidocConverterTest.class.getResource("/yaml/swagger_petstore.yaml").toURI());
+        Path outputDirectory = Paths.get("build/test/markdown/idxref");
+        FileUtils.deleteQuietly(outputDirectory.toFile());
+
+        //When
+        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
+                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
+                .withInterDocumentCrossReferences()
+                .build();
+
+        Swagger2MarkupConverter.from(file).withConfig(config).build()
+                .toFolder(outputDirectory);
+
+        //Then
+        String[] files = outputDirectory.toFile().list();
+        assertThat(files).hasSize(4).containsAll(expectedFiles);
+
+        Path expectedFilesDirectory = Paths.get(AsciidocConverterTest.class.getResource("/expected/markdown/idxref").toURI());
+        DiffUtils.assertThatAllFilesAreEqual(expectedFilesDirectory, outputDirectory, "testWithInterDocumentCrossReferences.html");
+    }
+
+    @Test
+    public void testWithSeparatedDefinitions() throws IOException, URISyntaxException {
+        //Given
+        Path file = Paths.get(MarkdownConverterTest.class.getResource("/yaml/swagger_petstore.yaml").toURI());
+        Path outputDirectory = Paths.get("build/test/markdown/generated");
+        FileUtils.deleteQuietly(outputDirectory.toFile());
+
+        //When
+        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
+                .withSeparatedDefinitions()
+                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
+                .build();
+        Swagger2MarkupConverter.from(file)
+                .withConfig(config)
+                .build()
+                .toFolder(outputDirectory);
+
+        //Then
+        String[] files = outputDirectory.toFile().list();
+        expectedFiles.add("definitions");
+        assertThat(files).hasSize(5).containsAll(expectedFiles);
+
+        Path definitionsDirectory = outputDirectory.resolve("definitions");
+        String[] definitions = definitionsDirectory.toFile().list();
+        assertThat(definitions).hasSize(5).containsAll(
+                asList("Category.md", "Order.md", "Pet.md", "Tag.md", "User.md"));
+    }
+
+    @Test
+    public void testWithResponseHeaders() throws IOException, URISyntaxException {
+        //Given
+        Path file = Paths.get(AsciidocConverterTest.class.getResource("/yaml/swagger_response_headers.yaml").toURI());
+        Path outputDirectory = Paths.get("build/test/markdown/response_headers");
+        FileUtils.deleteQuietly(outputDirectory.toFile());
+
+        //When
+        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
+                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
+                .build();
+        Swagger2MarkupConverter.from(file)
+                .withConfig(config)
+                .build()
+                .toFolder(outputDirectory);
+
+        //Then
+        String[] files = outputDirectory.toFile().list();
+        assertThat(files).hasSize(4).containsAll(expectedFiles);
+
+        Path expectedFilesDirectory = Paths.get(AsciidocConverterTest.class.getResource("/expected/markdown/response_headers").toURI());
+        DiffUtils.assertThatAllFilesAreEqual(expectedFilesDirectory, outputDirectory, "testWithResponseHeaders.html");
+    }
+
+    @Test
+    public void testHandlesComposition() throws IOException, URISyntaxException {
+        //Given
+        Path file = Paths.get(MarkdownConverterTest.class.getResource("/yaml/swagger_petstore.yaml").toURI());
+        Path outputDirectory = Paths.get("build/test/markdown/generated");
+        FileUtils.deleteQuietly(outputDirectory.toFile());
+
+        //When
+        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
+                .withSeparatedDefinitions()
+                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
+                .build();
+        Swagger2MarkupConverter.from(file)
+                .withConfig(config)
+                .build()
+                .toFolder(outputDirectory);
+
+        // Then
+        String[] files = outputDirectory.toFile().list();
+        expectedFiles.add("definitions");
+        assertThat(files).hasSize(5).containsAll(expectedFiles);
+        Path definitionsDirectory = outputDirectory.resolve("definitions");
+        verifyMarkdownContainsFieldsInTables(
+                definitionsDirectory.resolve("User.md").toFile(),
+                ImmutableMap.<String, Set<String>>builder()
+                        .put("User", ImmutableSet.of("id", "username", "firstName",
+                                "lastName", "email", "password", "phone", "userStatus"))
+                        .build()
+        );
+
+    }
 }

src/test/java/io/github/swagger2markup/assertions/DiffUtils.java

@@ -1,6 +1,6 @@
 /*
  *
- *  Copyright 2016 Robert Winkler
+ *  Copyright 2017 Robert Winkler
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.

src/test/java/io/github/swagger2markup/builder/MyExtension.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -46,7 +46,7 @@ public class MyExtension extends DefinitionsDocumentExtension {
         String definitionName = context.getDefinitionName().get();
         Model definitionModel = context.getModel().get();
 
-        if(position.equals(Position.DEFINITION_END)) {
+        if (position.equals(Position.DEFINITION_END)) {
             markupBuilder.sectionTitleLevel1(definitionName) //<4>
                     .paragraph(definitionModel.getDescription())
                     .importMarkup(new StringReader("*Markup*"), MarkupLanguage.ASCIIDOC);

src/test/java/io/github/swagger2markup/builder/MySwaggerModelExtension.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Robert Winkler
+ * Copyright 2017 Robert Winkler
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.