diff --git a/.travis.yml b/.travis.yml index e256b700..41768d4b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,6 +1,6 @@ language: java jdk: -- oraclejdk7 +- oraclejdk8 before_install: - chmod +x gradlew after_success: diff --git a/build.gradle b/build.gradle index bedba962..4ebbbb5b 100644 --- a/build.gradle +++ b/build.gradle @@ -22,8 +22,8 @@ apply from: 'gradle/coverage.gradle' apply from: 'gradle/documentation.gradle' tasks.withType(JavaCompile) { - sourceCompatibility = "1.7" - targetCompatibility = "1.7" + sourceCompatibility = "1.8" + 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 'commons-collections:commons-collections:3.2.2' + compile 'org.apache.commons:commons-configuration2:2.0' + 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' diff --git a/src/docs/asciidoc/extension_spi.adoc b/src/docs/asciidoc/extension_spi.adoc index 3bf0aa15..45307ec8 100644 --- a/src/docs/asciidoc/extension_spi.adoc +++ b/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 diff --git a/src/docs/asciidoc/introduction.adoc b/src/docs/asciidoc/introduction.adoc index 9775b1d8..059a5063 100644 --- a/src/docs/asciidoc/introduction.adoc +++ b/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 diff --git a/src/docs/asciidoc/usage_guide.adoc b/src/docs/asciidoc/usage_guide.adoc index dbea38b6..885fd83d 100644 --- a/src/docs/asciidoc/usage_guide.adoc +++ b/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. diff --git a/src/main/java/io/github/swagger2markup/Swagger2MarkupConverter.java b/src/main/java/io/github/swagger2markup/Swagger2MarkupConverter.java index 0440627e..b3d40c7f 100644 --- a/src/main/java/io/github/swagger2markup/Swagger2MarkupConverter.java +++ b/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 PathsDocumentBuilder(context, 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 SecurityDocumentBuilder(context, outputDirectory).build().writeToFile(outputDirectory.resolve(context.config.getSecurityDocument()), StandardCharsets.UTF_8); + new OverviewDocumentBuilder(context, extensionRegistry, outputDirectory).build().writeToFile(outputDirectory.resolve(context.config.getOverviewDocument()), StandardCharsets.UTF_8); + new PathsDocumentBuilder(context, extensionRegistry, outputDirectory).build().writeToFile(outputDirectory.resolve(context.config.getPathsDocument()), StandardCharsets.UTF_8); + new DefinitionsDocumentBuilder(context, extensionRegistry, outputDirectory).build().writeToFile(outputDirectory.resolve(context.config.getDefinitionsDocument()), 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 PathsDocumentBuilder(context, null).build().writeToFile(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND); - new DefinitionsDocumentBuilder(context, null).build().writeToFile(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND); - new SecurityDocumentBuilder(context, null).build().writeToFile(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND); + new OverviewDocumentBuilder(context,extensionRegistry, null).build().writeToFile(outputFile, StandardCharsets.UTF_8); + new PathsDocumentBuilder(context, extensionRegistry, 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, 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 PathsDocumentBuilder(context, null).build().writeToFileWithoutExtension(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND); - new DefinitionsDocumentBuilder(context, null).build().writeToFileWithoutExtension(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND); - new SecurityDocumentBuilder(context, null).build().writeToFileWithoutExtension(outputFile, StandardCharsets.UTF_8, StandardOpenOption.APPEND); + new OverviewDocumentBuilder(context, extensionRegistry, null).build().writeToFileWithoutExtension(outputFile, StandardCharsets.UTF_8); + new PathsDocumentBuilder(context, extensionRegistry, 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, 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 PathsDocumentBuilder(context, null).build().toString()); - sb.append(new DefinitionsDocumentBuilder(context, null).build().toString()); - sb.append(new SecurityDocumentBuilder(context, null).build().toString()); + sb.append(new OverviewDocumentBuilder(context,extensionRegistry, null).build().toString()); + sb.append(new PathsDocumentBuilder(context, extensionRegistry, null).build().toString()); + sb.append(new DefinitionsDocumentBuilder(context, extensionRegistry, 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; } diff --git a/src/main/java/io/github/swagger2markup/builder/Swagger2MarkupConfigBuilder.java b/src/main/java/io/github/swagger2markup/builder/Swagger2MarkupConfigBuilder.java index b50c17e1..57350f50 100644 --- a/src/main/java/io/github/swagger2markup/builder/Swagger2MarkupConfigBuilder.java +++ b/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 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); } diff --git a/src/main/java/io/github/swagger2markup/builder/Swagger2MarkupProperties.java b/src/main/java/io/github/swagger2markup/builder/Swagger2MarkupProperties.java index 4272cb08..c136b369 100644 --- a/src/main/java/io/github/swagger2markup/builder/Swagger2MarkupProperties.java +++ b/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.configuration.ConfigurationConverter; -import org.apache.commons.configuration.MapConfiguration; +import org.apache.commons.configuration2.Configuration; +import org.apache.commons.configuration2.ConfigurationConverter; +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 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 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(); } } diff --git a/src/main/java/io/github/swagger2markup/internal/document/MarkupDocument.java b/src/main/java/io/github/swagger2markup/internal/document/MarkupDocument.java index b497354b..2a9260c6 100644 --- a/src/main/java/io/github/swagger2markup/internal/document/MarkupDocument.java +++ b/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); } } diff --git a/src/main/java/io/github/swagger2markup/internal/document/builder/DefinitionsDocumentBuilder.java b/src/main/java/io/github/swagger2markup/internal/document/builder/DefinitionsDocumentBuilder.java index 372975c0..3eebe3fe 100644 --- a/src/main/java/io/github/swagger2markup/internal/document/builder/DefinitionsDocumentBuilder.java +++ b/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 IGNORED_DEFINITIONS = Collections.singletonList("Void"); private static final String DESCRIPTION_FILE_NAME = "description"; - public DefinitionsDocumentBuilder(Swagger2MarkupConverter.Context context, Path outputPath) { - super(context, outputPath); + public DefinitionsDocumentBuilder(Swagger2MarkupConverter.Context context, Swagger2MarkupExtensionRegistry extensionRegistry, Path 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); - } - } + defDocBuilder.writeToFileWithoutExtension(definitionFile, StandardCharsets.UTF_8); if (logger.isInfoEnabled()) { logger.info("Separate definition file produced: {}", definitionFile); } diff --git a/src/main/java/io/github/swagger2markup/internal/document/builder/MarkupDocumentBuilder.java b/src/main/java/io/github/swagger2markup/internal/document/builder/MarkupDocumentBuilder.java index cd8bcec1..103295cf 100644 --- a/src/main/java/io/github/swagger2markup/internal/document/builder/MarkupDocumentBuilder.java +++ b/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); - } + return markupDocBuilder.copy(false).importMarkup(new StringReader(markupText), globalContext.getConfig().getSwaggerMarkupLanguage()).toString().trim(); } protected void buildDescriptionParagraph(String description, MarkupDocBuilder docBuilder) { diff --git a/src/main/java/io/github/swagger2markup/internal/document/builder/OverviewDocumentBuilder.java b/src/main/java/io/github/swagger2markup/internal/document/builder/OverviewDocumentBuilder.java index 4b976051..0687782a 100644 --- a/src/main/java/io/github/swagger2markup/internal/document/builder/OverviewDocumentBuilder.java +++ b/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){ - super(context, outputPath); + public OverviewDocumentBuilder(Swagger2MarkupConverter.Context context, Swagger2MarkupExtensionRegistry extensionRegistry, Path 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); } } diff --git a/src/main/java/io/github/swagger2markup/internal/document/builder/PathsDocumentBuilder.java b/src/main/java/io/github/swagger2markup/internal/document/builder/PathsDocumentBuilder.java index 6e792337..21670792 100644 --- a/src/main/java/io/github/swagger2markup/internal/document/builder/PathsDocumentBuilder.java +++ b/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) { - super(globalContext, outputPath); + public PathsDocumentBuilder(Swagger2MarkupConverter.Context globalContext, Swagger2MarkupExtensionRegistry extensionRegistry, java.nio.file.Path 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); - } - } + pathDocBuilder.writeToFileWithoutExtension(operationFile, StandardCharsets.UTF_8); if (logger.isInfoEnabled()) { logger.info("Separate operation file produced: {}", operationFile); } diff --git a/src/main/java/io/github/swagger2markup/internal/document/builder/SecurityDocumentBuilder.java b/src/main/java/io/github/swagger2markup/internal/document/builder/SecurityDocumentBuilder.java index 49f3406b..457b9876 100644 --- a/src/main/java/io/github/swagger2markup/internal/document/builder/SecurityDocumentBuilder.java +++ b/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) { - super(context, outputPath); + public SecurityDocumentBuilder(Swagger2MarkupConverter.Context context, Swagger2MarkupExtensionRegistry extensionRegistry, Path 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); } } diff --git a/src/test/java/io/github/swagger2markup/DocumentationTest.java b/src/test/java/io/github/swagger2markup/DocumentationTest.java index b460ece9..138aef08 100644 --- a/src/test/java/io/github/swagger2markup/DocumentationTest.java +++ b/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.configuration.ConfigurationException; -import org.apache.commons.configuration.PropertiesConfiguration; +import org.apache.commons.configuration2.Configuration; +import org.apache.commons.configuration2.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(); diff --git a/src/test/java/io/github/swagger2markup/builder/MyExtension.java b/src/test/java/io/github/swagger2markup/builder/MyExtension.java index 3ae4066f..a06a2c72 100644 --- a/src/test/java/io/github/swagger2markup/builder/MyExtension.java +++ b/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 diff --git a/src/test/resources/expected/asciidoc/toFile/outputFile.adoc b/src/test/resources/expected/asciidoc/toFile/outputFile.adoc index e15fe0ce..45e88d27 100644 --- a/src/test/resources/expected/asciidoc/toFile/outputFile.adoc +++ b/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" ----