Upgrade to JDK8

.travis.yml

@@ -1,6 +1,6 @@
 language: java
 jdk:
-- oraclejdk7
+- oraclejdk8
 before_install:
 - chmod +x gradlew
 after_success:

build.gradle

@@ -22,8 +22,8 @@ apply from: 'gradle/coverage.gradle'
 apply from: 'gradle/documentation.gradle'
 
 tasks.withType(JavaCompile) {
-    sourceCompatibility = "1.7"
+    sourceCompatibility = "1.8"
-    targetCompatibility = "1.7"
+    targetCompatibility = "1.8"
     options.deprecation = true
     options.encoding = 'UTF-8'
     options.compilerArgs << "-Xlint:unchecked"
@@ -41,8 +41,8 @@ repositories {
 dependencies {
     compile 'io.github.swagger2markup:markup-document-builder:1.0.0-SNAPSHOT'
     compile 'io.swagger:swagger-compat-spec-parser:1.0.17'
-    compile 'commons-configuration:commons-configuration:1.10'
+    compile 'org.apache.commons:commons-configuration2:2.0'
-    compile 'commons-collections:commons-collections:3.2.2'
+    compile 'commons-beanutils:commons-beanutils:1.9.2'
     testCompile 'junit:junit:4.11'
     testCompile 'org.asciidoctor:asciidoctorj:1.5.4'
     testCompile 'ch.qos.logback:logback-classic:1.1.2'

src/docs/asciidoc/extension_spi.adoc

@@ -51,6 +51,12 @@ include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=sw
 
 ==== OverviewDocumentExtension
 
+The OverviewDocumentExtension allows to extend the overview document at three positions:
+
+* DOCUMENT_BEFORE: Before the 
+* DOCUMENT_START:
+* DOCUMENT_BEFORE:
+
 ==== PathsDocumentExtension
 
 ==== SecurityDocumentExtension

src/docs/asciidoc/introduction.adoc

@@ -8,7 +8,7 @@ Swagger2Markup converts a Swagger JSON or YAML specification into either **Ascii
 
 You can use Swagger2Markup to convert your contract-first Swagger YAML file into Markup. As an alternative, you can choose the code-first approach and use Swagger2Markup together with https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-JAX-RS-Project-Setup-1.5.X[Swagger JAX-RS], https://github.com/springfox/springfox[Springfox] or https://github.com/spring-projects/spring-restdocs[spring-restdocs]. If you are are Gradle or Maven user, you can also use the https://github.com/Swagger2Markup/swagger2markup-gradle-plugin[Swagger2Markup Gradle Plugin] or https://github.com/redowl/swagger2markup-maven-plugin[Swagger2markup Maven Plugin].
 
-NOTE: The project requires at least JDK 7.
+NOTE: The project requires at least JDK 8.
 
 ===  AsciiDoc
 

src/docs/asciidoc/usage_guide.adoc

@@ -113,7 +113,7 @@ Configuration parameters may be loaded from the following sources using Apache C
 include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=swagger2MarkupConfigFromCommonsConfiguration]
 ----
 
-1. Create a Commons `Configuraton` object. Different configuration sources can be mixed using a `CombinedConfigurationBuilder` or a `CombinedConfiguration`. 
+1. Create an Apache Commons `Configuraton` object using the proper ConfigurationBuilder.
 2. Create a `Swagger2MarkupConfigBuilder` using the proper constructor.
 
 === Available Swagger2Markup properties
@@ -187,3 +187,7 @@ The following tables list all available Swagger2Markup properties:
 |swagger2markup.inlineSchemaDepthLevel| Specifies maximum depth level for inline object schema displaying | Any Integer | 0
 |swagger2markup.flatBodyEnabled| Optionally isolate the body parameter, if any, from other parameters | true, false | false
 |===
+
+== Logging
+
+Swagger2Markup uses http://www.slf4j.org/[SLF4J] for all internal logging, but leaves the underlying log implementation open.

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

@@ -15,7 +15,6 @@
  */
 package io.github.swagger2markup;
 
-import com.google.common.annotations.VisibleForTesting;
 import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
 import io.github.swagger2markup.builder.Swagger2MarkupExtensionRegistryBuilder;
 import io.github.swagger2markup.internal.document.builder.DefinitionsDocumentBuilder;
@@ -46,8 +45,11 @@ public class Swagger2MarkupConverter {
 
     private Context context;
 
-    public Swagger2MarkupConverter(Context globalContext) {
+    private Swagger2MarkupExtensionRegistry extensionRegistry;
+
+    public Swagger2MarkupConverter(Context globalContext, Swagger2MarkupExtensionRegistry extensionRegistry) {
         this.context = globalContext;
+        this.extensionRegistry = extensionRegistry;
     }
 
     /**
@@ -55,7 +57,6 @@ public class Swagger2MarkupConverter {
      *
      * @return the global Context
      */
-    @VisibleForTesting
     Context getContext(){
         return context;
     }
@@ -98,9 +99,8 @@ public class Swagger2MarkupConverter {
      *
      * @param swaggerString the Swagger YAML or JSON String.
      * @return a Swagger2MarkupConverter
-     * @throws java.io.IOException if String can not be parsed
      */
-    public static Builder from(String swaggerString) throws IOException {
+    public static Builder from(String swaggerString) {
         Validate.notEmpty(swaggerString, "swaggerString must not be null");
         return from(new StringReader(swaggerString));
     }
@@ -110,11 +110,15 @@ public class Swagger2MarkupConverter {
      *
      * @param swaggerReader the Swagger YAML or JSON reader.
      * @return a Swagger2MarkupConverter
-     * @throws java.io.IOException if source can not be parsed
      */
-    public static Builder from(Reader swaggerReader) throws IOException {
+    public static Builder from(Reader swaggerReader) {
         Validate.notNull(swaggerReader, "swaggerReader must not be null");
-        Swagger swagger = new SwaggerParser().parse(IOUtils.toString(swaggerReader));
+        Swagger swagger;
+        try {
+            swagger = new SwaggerParser().parse(IOUtils.toString(swaggerReader));
+        } catch (IOException e) {
+            throw new RuntimeException("Swagger source can not be parsed", e);
+        }
         if (swagger == null)
             throw new IllegalArgumentException("Swagger source is in a wrong format");
 
@@ -125,17 +129,16 @@ public class Swagger2MarkupConverter {
      * Builds the documents and stores the files in the given {@code outputDirectory}.
      *
      * @param outputDirectory the output directory path
-     * @throws IOException if the files cannot be written
      */
-    public void toFolder(Path outputDirectory) throws IOException {
+    public void toFolder(Path outputDirectory){
         Validate.notNull(outputDirectory, "outputDirectory must not be null");
 
         applySwaggerExtensions();
         
-        new OverviewDocumentBuilder(context, outputDirectory).build().writeToFile(outputDirectory.resolve(context.config.getOverviewDocument()), StandardCharsets.UTF_8);
+        new OverviewDocumentBuilder(context, extensionRegistry, outputDirectory).build().writeToFile(outputDirectory.resolve(context.config.getOverviewDocument()), StandardCharsets.UTF_8);
-        new PathsDocumentBuilder(context, outputDirectory).build().writeToFile(outputDirectory.resolve(context.config.getPathsDocument()), StandardCharsets.UTF_8);
+        new PathsDocumentBuilder(context, extensionRegistry, outputDirectory).build().writeToFile(outputDirectory.resolve(context.config.getPathsDocument()), StandardCharsets.UTF_8);
-        new DefinitionsDocumentBuilder(context, outputDirectory).build().writeToFile(outputDirectory.resolve(context.config.getDefinitionsDocument()), StandardCharsets.UTF_8);
+        new DefinitionsDocumentBuilder(context, extensionRegistry, outputDirectory).build().writeToFile(outputDirectory.resolve(context.config.getDefinitionsDocument()), StandardCharsets.UTF_8);
-        new SecurityDocumentBuilder(context, outputDirectory).build().writeToFile(outputDirectory.resolve(context.config.getSecurityDocument()), StandardCharsets.UTF_8);
+        new SecurityDocumentBuilder(context, extensionRegistry, outputDirectory).build().writeToFile(outputDirectory.resolve(context.config.getSecurityDocument()), StandardCharsets.UTF_8);
     }
 
     /**
@@ -143,30 +146,28 @@ public class Swagger2MarkupConverter {
      * An extension identifying the markup language will be automatically added to file name.
      *
      * @param outputFile the output file
-     * @throws IOException if the files cannot be written
      */
-    public void toFile(Path outputFile) throws IOException {
+    public void toFile(Path outputFile) {
         Validate.notNull(outputFile, "outputFile must not be null");
 
-        new OverviewDocumentBuilder(context, null).build().writeToFile(outputFile, StandardCharsets.UTF_8);
+        new OverviewDocumentBuilder(context,extensionRegistry,  null).build().writeToFile(outputFile, StandardCharsets.UTF_8);
-        new PathsDocumentBuilder(context, null).build().writeToFile(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND);
+        new PathsDocumentBuilder(context, extensionRegistry, null).build().writeToFile(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND);
-        new DefinitionsDocumentBuilder(context, null).build().writeToFile(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND);
+        new DefinitionsDocumentBuilder(context, extensionRegistry, null).build().writeToFile(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND);
-        new SecurityDocumentBuilder(context, null).build().writeToFile(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND);
+        new SecurityDocumentBuilder(context, extensionRegistry, null).build().writeToFile(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND);
     }
 
     /**
      * Builds the document and stores it in the given {@code outputFile}.
      *
      * @param outputFile the output file
-     * @throws IOException if the files cannot be written
      */
-    public void toFileWithoutExtension(Path outputFile) throws IOException {
+    public void toFileWithoutExtension(Path outputFile){
         Validate.notNull(outputFile, "outputFile must not be null");
 
-        new OverviewDocumentBuilder(context, null).build().writeToFileWithoutExtension(outputFile, StandardCharsets.UTF_8);
+        new OverviewDocumentBuilder(context, extensionRegistry, null).build().writeToFileWithoutExtension(outputFile, StandardCharsets.UTF_8);
-        new PathsDocumentBuilder(context, null).build().writeToFileWithoutExtension(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND);
+        new PathsDocumentBuilder(context, extensionRegistry, null).build().writeToFileWithoutExtension(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND);
-        new DefinitionsDocumentBuilder(context, null).build().writeToFileWithoutExtension(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND);
+        new DefinitionsDocumentBuilder(context, extensionRegistry, null).build().writeToFileWithoutExtension(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND);
-        new SecurityDocumentBuilder(context, null).build().writeToFileWithoutExtension(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND);
+        new SecurityDocumentBuilder(context, extensionRegistry, null).build().writeToFileWithoutExtension(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND);
     }
 
     /**
@@ -178,15 +179,15 @@ public class Swagger2MarkupConverter {
         applySwaggerExtensions();
         
         StringBuilder sb = new StringBuilder();
-        sb.append(new OverviewDocumentBuilder(context, null).build().toString());
+        sb.append(new OverviewDocumentBuilder(context,extensionRegistry,  null).build().toString());
-        sb.append(new PathsDocumentBuilder(context, null).build().toString());
+        sb.append(new PathsDocumentBuilder(context, extensionRegistry, null).build().toString());
-        sb.append(new DefinitionsDocumentBuilder(context, null).build().toString());
+        sb.append(new DefinitionsDocumentBuilder(context, extensionRegistry, null).build().toString());
-        sb.append(new SecurityDocumentBuilder(context, null).build().toString());
+        sb.append(new SecurityDocumentBuilder(context, extensionRegistry, null).build().toString());
         return sb.toString();
     }
 
     private void applySwaggerExtensions() {
-        for (SwaggerModelExtension swaggerModelExtension : context.extensionRegistry.getSwaggerModelExtensions()) {
+        for (SwaggerModelExtension swaggerModelExtension : extensionRegistry.getSwaggerModelExtensions()) {
             swaggerModelExtension.apply(context.getSwagger());
         }
     }
@@ -252,7 +253,7 @@ public class Swagger2MarkupConverter {
         }
 
         public Builder withExtensionRegistry(Swagger2MarkupExtensionRegistry registry) {
-            Validate.notNull(config, "registry must not be null");
+            Validate.notNull(registry, "registry must not be null");
             this.extensionRegistry = registry;
             return this;
         }
@@ -264,11 +265,11 @@ public class Swagger2MarkupConverter {
             if (extensionRegistry == null)
                 extensionRegistry = new Swagger2MarkupExtensionRegistryBuilder().build();
 
-            Context context = new Context(config, extensionRegistry, swagger, swaggerLocation);
+            Context context = new Context(config, swagger, swaggerLocation);
 
             initExtensions(context);
 
-            return new Swagger2MarkupConverter(context);
+            return new Swagger2MarkupConverter(context, extensionRegistry);
         }
 
         private void initExtensions(Context context) {
@@ -291,13 +292,11 @@ public class Swagger2MarkupConverter {
 
     public static class Context {
         private Swagger2MarkupConfig config;
-        private Swagger2MarkupExtensionRegistry extensionRegistry;
         private Swagger swagger;
         private URI swaggerLocation;
 
-        Context(Swagger2MarkupConfig config, Swagger2MarkupExtensionRegistry extensionRegistry, Swagger swagger, URI swaggerLocation) {
+        Context(Swagger2MarkupConfig config, Swagger swagger, URI swaggerLocation) {
             this.config = config;
-            this.extensionRegistry = extensionRegistry;
             this.swagger = swagger;
             this.swaggerLocation = swaggerLocation;
         }
@@ -306,10 +305,6 @@ public class Swagger2MarkupConverter {
             return config;
         }
 
-        public Swagger2MarkupExtensionRegistry getExtensionRegistry() {
-            return extensionRegistry;
-        }
-
         public Swagger getSwagger() {
             return swagger;
         }

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

@@ -16,18 +16,20 @@
 package io.github.swagger2markup.builder;
 
 import com.google.common.base.Function;
-import com.google.common.base.Optional;
 import com.google.common.collect.Ordering;
-import io.github.swagger2markup.markup.builder.LineSeparator;
-import io.github.swagger2markup.markup.builder.MarkupLanguage;
 import io.github.swagger2markup.GroupBy;
 import io.github.swagger2markup.Language;
 import io.github.swagger2markup.OrderBy;
 import io.github.swagger2markup.Swagger2MarkupConfig;
+import io.github.swagger2markup.markup.builder.LineSeparator;
+import io.github.swagger2markup.markup.builder.MarkupLanguage;
 import io.github.swagger2markup.model.PathOperation;
 import io.swagger.models.HttpMethod;
 import io.swagger.models.parameters.Parameter;
-import org.apache.commons.configuration.*;
+import org.apache.commons.configuration2.*;
+import org.apache.commons.configuration2.builder.FileBasedConfigurationBuilder;
+import org.apache.commons.configuration2.builder.fluent.Parameters;
+import org.apache.commons.configuration2.ex.ConfigurationException;
 import org.apache.commons.lang3.StringUtils;
 import org.apache.commons.lang3.Validate;
 import org.slf4j.Logger;
@@ -37,10 +39,9 @@ import java.net.URI;
 import java.nio.file.Path;
 import java.util.Comparator;
 import java.util.Map;
+import java.util.Optional;
 import java.util.Properties;
 
-import static io.github.swagger2markup.builder.Swagger2MarkupProperties.EXTENSION_PREFIX;
-import static io.github.swagger2markup.builder.Swagger2MarkupProperties.PROPERTIES_PREFIX;
 import static io.github.swagger2markup.builder.Swagger2MarkupProperties.*;
 
 public class Swagger2MarkupConfigBuilder  {
@@ -99,8 +100,13 @@ public class Swagger2MarkupConfigBuilder  {
         CompositeConfiguration compositeConfiguration = new CompositeConfiguration();
         compositeConfiguration.addConfiguration(new SystemConfiguration());
         compositeConfiguration.addConfiguration(configuration);
+
+        FileBasedConfigurationBuilder<PropertiesConfiguration> builder =
+                new FileBasedConfigurationBuilder<>(PropertiesConfiguration.class)
+                        .configure(new Parameters().fileBased().setFileName(PROPERTIES_DEFAULT));
+
         try {
-            compositeConfiguration.addConfiguration(new PropertiesConfiguration(PROPERTIES_DEFAULT));
+            compositeConfiguration.addConfiguration(builder.getConfiguration());
         } catch (ConfigurationException e) {
             throw new RuntimeException(String.format("Can't load default properties '%s'", PROPERTIES_DEFAULT), e);
         }

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

@@ -15,21 +15,21 @@
  */
 package io.github.swagger2markup.builder;
 
-import com.google.common.base.Optional;
-import io.github.swagger2markup.markup.builder.MarkupLanguage;
 import io.github.swagger2markup.GroupBy;
 import io.github.swagger2markup.Language;
 import io.github.swagger2markup.OrderBy;
+import io.github.swagger2markup.markup.builder.MarkupLanguage;
 import org.apache.commons.collections4.IteratorUtils;
-import org.apache.commons.configuration.Configuration;
+import org.apache.commons.configuration2.Configuration;
-import org.apache.commons.configuration.ConfigurationConverter;
+import org.apache.commons.configuration2.ConfigurationConverter;
-import org.apache.commons.configuration.MapConfiguration;
+import org.apache.commons.configuration2.MapConfiguration;
 
 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;
 
 public class Swagger2MarkupProperties {
@@ -91,7 +91,7 @@ public class Swagger2MarkupProperties {
      * @param key the property name to resolve
      */
     public Optional<String> getString(String key){
-        return Optional.fromNullable(configuration.getString(key));
+        return Optional.ofNullable(configuration.getString(key));
     }
 
     /**
@@ -119,7 +119,7 @@ public class Swagger2MarkupProperties {
      * @param key the property name to resolve
      */
     public Optional<Integer> getInteger(String key){
-        return Optional.fromNullable(configuration.getInteger(key, null));
+        return Optional.ofNullable(configuration.getInteger(key, null));
     }
 
     /**
@@ -168,7 +168,7 @@ public class Swagger2MarkupProperties {
         if(property.isPresent()){
             return Optional.of(URI.create(property.get()));
         }else{
-            return Optional.absent();
+            return Optional.empty();
         }
     }
 
@@ -196,7 +196,7 @@ public class Swagger2MarkupProperties {
         if(property.isPresent()){
             return Optional.of(Paths.get(property.get()));
         }else{
-            return Optional.absent();
+            return Optional.empty();
         }
     }
 
@@ -223,7 +223,7 @@ public class Swagger2MarkupProperties {
         if(property.isPresent()){
             return Optional.of(MarkupLanguage.valueOf(property.get()));
         }else{
-            return Optional.absent();
+            return Optional.empty();
         }
     }
 

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

@@ -17,7 +17,6 @@ package io.github.swagger2markup.internal.document;
 
 import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
 
-import java.io.IOException;
 import java.nio.charset.Charset;
 import java.nio.file.OpenOption;
 import java.nio.file.Path;
@@ -44,9 +43,8 @@ public class MarkupDocument {
      * @param file    the generated file
      * @param charset the the charset to use for encoding
      * @param options the file open options
-     * @throws IOException if the file cannot be written
      */
-    public void writeToFile(Path file, Charset charset, OpenOption... options) throws IOException {
+    public void writeToFile(Path file, Charset charset, OpenOption... options) {
         markupDocBuilder.writeToFile(file, charset, options);
     }
 
@@ -56,9 +54,8 @@ public class MarkupDocument {
      * @param file    the generated file
      * @param charset the the charset to use for encoding
      * @param options the file open options
-     * @throws IOException if the file cannot be written
      */
-    public void writeToFileWithoutExtension(Path file, Charset charset, OpenOption... options) throws IOException {
+    public void writeToFileWithoutExtension(Path file, Charset charset, OpenOption... options) {
         markupDocBuilder.writeToFileWithoutExtension(file, charset, options);
     }
 }

src/main/java/io/github/swagger2markup/internal/document/builder/DefinitionsDocumentBuilder.java

@@ -17,6 +17,7 @@ package io.github.swagger2markup.internal.document.builder;
 
 import com.google.common.base.Optional;
 import com.google.common.collect.ImmutableMap;
+import io.github.swagger2markup.Swagger2MarkupExtensionRegistry;
 import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
 import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.internal.document.MarkupDocument;
@@ -58,8 +59,8 @@ public class DefinitionsDocumentBuilder extends MarkupDocumentBuilder {
     private static final List<String> IGNORED_DEFINITIONS = Collections.singletonList("Void");
     private static final String DESCRIPTION_FILE_NAME = "description";
 
-    public DefinitionsDocumentBuilder(Swagger2MarkupConverter.Context context, Path outputPath) {
+    public DefinitionsDocumentBuilder(Swagger2MarkupConverter.Context context, Swagger2MarkupExtensionRegistry extensionRegistry, Path outputPath) {
-        super(context, outputPath);
+        super(context, extensionRegistry, outputPath);
 
         ResourceBundle labels = ResourceBundle.getBundle("io/github/swagger2markup/lang/labels", config.getOutputLanguage().toLocale());
         DEFINITIONS = labels.getString("definitions");
@@ -132,7 +133,7 @@ public class DefinitionsDocumentBuilder extends MarkupDocumentBuilder {
      * @param context context
      */
     private void applyDefinitionsDocumentExtension(Context context) {
-        for (DefinitionsDocumentExtension extension : globalContext.getExtensionRegistry().getDefinitionsDocumentExtensions()) {
+        for (DefinitionsDocumentExtension extension : extensionRegistry.getDefinitionsDocumentExtensions()) {
             extension.apply(context);
         }
     }
@@ -163,13 +164,7 @@ public class DefinitionsDocumentBuilder extends MarkupDocumentBuilder {
             MarkupDocBuilder defDocBuilder = this.markupDocBuilder.copy(false);
             buildDefinition(definitions, definitionName, model, defDocBuilder);
             Path definitionFile = outputPath.resolve(resolveDefinitionDocument(definitionName));
-            try {
             defDocBuilder.writeToFileWithoutExtension(definitionFile, StandardCharsets.UTF_8);
-            } catch (IOException e) {
-                if (logger.isWarnEnabled()) {
-                    logger.warn(String.format("Failed to write definition file: %s", definitionFile), e);
-                }
-            }
             if (logger.isInfoEnabled()) {
                 logger.info("Separate definition file produced: {}", definitionFile);
             }

src/main/java/io/github/swagger2markup/internal/document/builder/MarkupDocumentBuilder.java

@@ -15,6 +15,7 @@
  */
 package io.github.swagger2markup.internal.document.builder;
 
+import io.github.swagger2markup.Swagger2MarkupExtensionRegistry;
 import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
 import io.github.swagger2markup.markup.builder.MarkupDocBuilders;
 import io.github.swagger2markup.markup.builder.MarkupLanguage;
@@ -65,12 +66,14 @@ public abstract class MarkupDocumentBuilder {
     protected Logger logger = LoggerFactory.getLogger(getClass());
 
     protected Swagger2MarkupConverter.Context globalContext;
+    protected Swagger2MarkupExtensionRegistry extensionRegistry;
     protected Swagger2MarkupConfig config;
     protected MarkupDocBuilder markupDocBuilder;
     protected Path outputPath;
 
-    MarkupDocumentBuilder(Swagger2MarkupConverter.Context globalContext, Path outputPath) {
+    MarkupDocumentBuilder(Swagger2MarkupConverter.Context globalContext, Swagger2MarkupExtensionRegistry extensionRegistry, Path outputPath) {
         this.globalContext = globalContext;
+        this.extensionRegistry = extensionRegistry;
         this.config = globalContext.getConfig();
         this.outputPath = outputPath;
 
@@ -162,11 +165,7 @@ public abstract class MarkupDocumentBuilder {
      * @return converted markup text
      */
     protected String swaggerMarkupDescription(String markupText) {
-        try {
         return markupDocBuilder.copy(false).importMarkup(new StringReader(markupText), globalContext.getConfig().getSwaggerMarkupLanguage()).toString().trim();
-        } catch (IOException e) {
-            throw new RuntimeException(e);
-        }
     }
 
     protected void buildDescriptionParagraph(String description, MarkupDocBuilder docBuilder) {

src/main/java/io/github/swagger2markup/internal/document/builder/OverviewDocumentBuilder.java

@@ -16,6 +16,7 @@
 package io.github.swagger2markup.internal.document.builder;
 
 import io.github.swagger2markup.Swagger2MarkupConverter;
+import io.github.swagger2markup.Swagger2MarkupExtensionRegistry;
 import io.github.swagger2markup.internal.document.MarkupDocument;
 import io.github.swagger2markup.spi.OverviewDocumentExtension;
 import io.swagger.models.*;
@@ -49,8 +50,8 @@ public class OverviewDocumentBuilder extends MarkupDocumentBuilder {
     private final String BASE_PATH;
     private final String SCHEMES;
 
-    public OverviewDocumentBuilder(Swagger2MarkupConverter.Context context, Path outputPath){
+    public OverviewDocumentBuilder(Swagger2MarkupConverter.Context context, Swagger2MarkupExtensionRegistry extensionRegistry, Path outputPath){
-        super(context, outputPath);
+        super(context, extensionRegistry, outputPath);
 
         ResourceBundle labels = ResourceBundle.getBundle("io/github/swagger2markup/lang/labels", config.getOutputLanguage().toLocale());
         OVERVIEW = labels.getString("overview");
@@ -192,7 +193,7 @@ public class OverviewDocumentBuilder extends MarkupDocumentBuilder {
      * @param context context
      */
     private void applyOverviewDocumentExtension(Context context) {
-        for (OverviewDocumentExtension extension : globalContext.getExtensionRegistry().getOverviewDocumentExtensions()) {
+        for (OverviewDocumentExtension extension : extensionRegistry.getOverviewDocumentExtensions()) {
             extension.apply(context);
         }
     }

src/main/java/io/github/swagger2markup/internal/document/builder/PathsDocumentBuilder.java

@@ -18,6 +18,7 @@ package io.github.swagger2markup.internal.document.builder;
 import com.google.common.base.Joiner;
 import com.google.common.base.Optional;
 import com.google.common.collect.Multimap;
+import io.github.swagger2markup.Swagger2MarkupExtensionRegistry;
 import io.github.swagger2markup.markup.builder.*;
 import io.github.swagger2markup.GroupBy;
 import io.github.swagger2markup.Swagger2MarkupConverter;
@@ -87,8 +88,8 @@ public class PathsDocumentBuilder extends MarkupDocumentBuilder {
     private static final String DESCRIPTION_FILE_NAME = "description";
 
 
-    public PathsDocumentBuilder(Swagger2MarkupConverter.Context globalContext, java.nio.file.Path outputPath) {
+    public PathsDocumentBuilder(Swagger2MarkupConverter.Context globalContext, Swagger2MarkupExtensionRegistry extensionRegistry,  java.nio.file.Path outputPath) {
-        super(globalContext, outputPath);
+        super(globalContext, extensionRegistry, outputPath);
 
         ResourceBundle labels = ResourceBundle.getBundle("io/github/swagger2markup/lang/labels", config.getOutputLanguage().toLocale());
         RESPONSE = labels.getString("response");
@@ -227,7 +228,7 @@ public class PathsDocumentBuilder extends MarkupDocumentBuilder {
      * @param context context
      */
     private void applyPathsDocumentExtension(Context context) {
-        for (PathsDocumentExtension extension : globalContext.getExtensionRegistry().getPathsDocumentExtensions()) {
+        for (PathsDocumentExtension extension : extensionRegistry.getPathsDocumentExtensions()) {
             extension.apply(context);
         }
     }
@@ -255,14 +256,7 @@ public class PathsDocumentBuilder extends MarkupDocumentBuilder {
             MarkupDocBuilder pathDocBuilder = this.markupDocBuilder.copy(false);
             buildOperation(operation, pathDocBuilder);
             java.nio.file.Path operationFile = outputPath.resolve(resolveOperationDocument(operation));
-
-            try {
              pathDocBuilder.writeToFileWithoutExtension(operationFile, StandardCharsets.UTF_8);
-            } catch (IOException e) {
-                if (logger.isWarnEnabled()) {
-                    logger.warn(String.format("Failed to write operation file: %s", operationFile), e);
-                }
-            }
             if (logger.isInfoEnabled()) {
                 logger.info("Separate operation file produced: {}", operationFile);
             }

src/main/java/io/github/swagger2markup/internal/document/builder/SecurityDocumentBuilder.java

@@ -15,6 +15,7 @@
  */
 package io.github.swagger2markup.internal.document.builder;
 
+import io.github.swagger2markup.Swagger2MarkupExtensionRegistry;
 import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
 import io.github.swagger2markup.markup.builder.MarkupTableColumn;
 import io.github.swagger2markup.Swagger2MarkupConverter;
@@ -47,8 +48,8 @@ public class SecurityDocumentBuilder extends MarkupDocumentBuilder {
     private final String AUTHORIZATION_URL;
     private final String TOKEN_URL;
 
-    public SecurityDocumentBuilder(Swagger2MarkupConverter.Context context, Path outputPath) {
+    public SecurityDocumentBuilder(Swagger2MarkupConverter.Context context, Swagger2MarkupExtensionRegistry extensionRegistry, Path outputPath) {
-        super(context, outputPath);
+        super(context, extensionRegistry, outputPath);
 
         ResourceBundle labels = ResourceBundle.getBundle("io/github/swagger2markup/lang/labels", config.getOutputLanguage().toLocale());
         SECURITY = labels.getString("security");
@@ -131,7 +132,7 @@ public class SecurityDocumentBuilder extends MarkupDocumentBuilder {
      * @param context context
      */
     private void applySecurityDocumentExtension(Context context) {
-        for (SecurityDocumentExtension extension : globalContext.getExtensionRegistry().getSecurityDocumentExtensions()) {
+        for (SecurityDocumentExtension extension : extensionRegistry.getSecurityDocumentExtensions()) {
             extension.apply(context);
         }
     }

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

@@ -20,9 +20,11 @@ import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
 import io.github.swagger2markup.builder.Swagger2MarkupExtensionRegistryBuilder;
 import io.github.swagger2markup.builder.Swagger2MarkupProperties;
 import io.github.swagger2markup.markup.builder.MarkupLanguage;
-import org.apache.commons.configuration.Configuration;
+import org.apache.commons.configuration2.Configuration;
-import org.apache.commons.configuration.ConfigurationException;
+import org.apache.commons.configuration2.PropertiesConfiguration;
-import org.apache.commons.configuration.PropertiesConfiguration;
+import org.apache.commons.configuration2.builder.FileBasedConfigurationBuilder;
+import org.apache.commons.configuration2.builder.fluent.Parameters;
+import org.apache.commons.configuration2.ex.ConfigurationException;
 
 import java.io.IOException;
 import java.net.URISyntaxException;
@@ -150,7 +152,10 @@ public class DocumentationTest {
         Path localSwaggerFile = Paths.get("/path/to/swagger.yaml");
 
         // tag::swagger2MarkupConfigFromCommonsConfiguration[]
-        Configuration configuration = new PropertiesConfiguration("config.properties"); //<1>
+        Configuration configuration =
+                new FileBasedConfigurationBuilder<>(PropertiesConfiguration.class)
+                        .configure(new Parameters().fileBased().setFileName("config.properties"))
+                .getConfiguration(); //<1>
 
         Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder(configuration) //<2>
                 .build();

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

@@ -19,13 +19,20 @@ import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
 import io.github.swagger2markup.spi.DefinitionsDocumentExtension;
 import io.swagger.models.Model;
+import io.swagger.models.Swagger;
 
 // tag::MyExtension[]
 public class MyExtension extends DefinitionsDocumentExtension {
 
+    private static final String EXTENSION_ID = "myExtension";
+    private String extensionProperty;
+
     @Override
     public void init(Swagger2MarkupConverter.Context globalContext) {
         // init is executed once
+        Swagger2MarkupProperties extensionProperties = globalContext.getConfig().getExtensionsProperties();
+        extensionProperty = extensionProperties.getRequiredString(EXTENSION_ID + ".propertyName");
+        Swagger model = globalContext.getSwagger();
     }
 
     @Override

src/test/resources/expected/asciidoc/toFile/outputFile.adoc

@@ -93,13 +93,13 @@ POST /pets
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/pets"
 ----
 
 
-==== Request body
+===== Request body
 ----
 {
   "id" : 0,
@@ -191,13 +191,13 @@ PUT /pets
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/pets"
 ----
 
 
-==== Request body
+===== Request body
 ----
 {
   "id" : 0,
@@ -288,13 +288,13 @@ Multiple status values can be provided with comma seperated strings
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/pets/findByStatus"
 ----
 
 
-==== Request query
+===== Request query
 ----
 {
   "status" : "string"
@@ -304,7 +304,7 @@ Multiple status values can be provided with comma seperated strings
 
 ==== Example HTTP response
 
-==== Response 200
+===== Response 200
 ----
 "array"
 ----
@@ -382,13 +382,13 @@ Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/pets/findByTags"
 ----
 
 
-==== Request query
+===== Request query
 ----
 {
   "tags" : "string"
@@ -398,7 +398,7 @@ Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3
 
 ==== Example HTTP response
 
-==== Response 200
+===== Response 200
 ----
 "array"
 ----
@@ -460,13 +460,13 @@ POST /pets/{petId}
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/pets/string"
 ----
 
 
-==== Request formData
+===== Request formData
 ----
 "string"
 ----
@@ -554,7 +554,7 @@ Returns a pet when ID < 10. ID > 10 or nonintegers will simulate API error
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/pets/0"
 ----
@@ -562,7 +562,7 @@ Returns a pet when ID < 10. ID > 10 or nonintegers will simulate API error
 
 ==== Example HTTP response
 
-==== Response 200
+===== Response 200
 ----
 {
   "id" : 0,
@@ -631,13 +631,13 @@ DELETE /pets/{petId}
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/pets/0"
 ----
 
 
-==== Request header
+===== Request header
 ----
 "string"
 ----
@@ -702,13 +702,13 @@ POST /stores/order
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/stores/order"
 ----
 
 
-==== Request body
+===== Request body
 ----
 {
   "id" : 0,
@@ -723,7 +723,7 @@ POST /stores/order
 
 ==== Example HTTP response
 
-==== Response 200
+===== Response 200
 ----
 {
   "id" : 0,
@@ -808,7 +808,7 @@ For valid response try integer IDs with value <= 5 or > 10. Other values w
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/stores/order/string"
 ----
@@ -816,7 +816,7 @@ For valid response try integer IDs with value <= 5 or > 10. Other values w
 
 ==== Example HTTP response
 
-==== Response 200
+===== Response 200
 ----
 {
   "id" : 0,
@@ -882,7 +882,7 @@ For valid response try integer IDs with value < 1000. Anything above 1000 or
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/stores/order/string"
 ----
@@ -932,13 +932,13 @@ This can only be done by the logged in user.
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/users"
 ----
 
 
-==== Request body
+===== Request body
 ----
 {
   "id" : 0,
@@ -993,13 +993,13 @@ POST /users/createWithArray
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/users/createWithArray"
 ----
 
 
-==== Request body
+===== Request body
 ----
 [ {
   "id" : 0,
@@ -1054,13 +1054,13 @@ POST /users/createWithList
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/users/createWithList"
 ----
 
 
-==== Request body
+===== Request body
 ----
 [ {
   "id" : 0,
@@ -1135,13 +1135,13 @@ GET /users/login
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/users/login"
 ----
 
 
-==== Request query
+===== Request query
 ----
 {
   "password" : "string",
@@ -1152,7 +1152,7 @@ GET /users/login
 
 ==== Example HTTP response
 
-==== Response 200
+===== Response 200
 ----
 "string"
 ----
@@ -1189,7 +1189,7 @@ GET /users/logout
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/users/logout"
 ----
@@ -1263,7 +1263,7 @@ GET /users/{username}
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/users/string"
 ----
@@ -1271,7 +1271,7 @@ GET /users/{username}
 
 ==== Example HTTP response
 
-==== Response 200
+===== Response 200
 ----
 {
   "id" : 0,
@@ -1340,13 +1340,13 @@ This can only be done by the logged in user.
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/users/string"
 ----
 
 
-==== Request body
+===== Request body
 ----
 {
   "id" : 0,
@@ -1414,7 +1414,7 @@ This can only be done by the logged in user.
 
 ==== Example HTTP request
 
-==== Request path
+===== Request path
 ----
 "/users/string"
 ----