Merge pull request #3150 from patrickfav/feature/3133-maven-config

Add swagger config file option to maven plugin (#3133)

Author: frantuma

modules/swagger-maven-plugin/README.md

@@ -56,6 +56,34 @@ to `swagger` [configuration property](https://github.com/swagger-api/swagger-cor
 </project>
 ```
 
+### Configuration example with provided Swagger configuration file
+ 
+ ``` 
+<project>
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>io.swagger.core.v3</groupId>
+                <artifactId>swagger-maven-plugin</artifactId>
+                <version>2.0.8-SNAPSHOT</version>
+                <configuration>
+                    <outputFileName>openapi</outputFileName>
+                    <outputPath>${project.build.directory}/generatedtest</outputPath>
+                    <configurationFilePath>${project.basedir}/src/main/resources/configurationFile.yaml</configurationFilePath>
+                </configuration>
+                <executions>
+                    <execution>
+                        <phase>compile</phase>
+                        <goals>
+                            <goal>resolve</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+    ...
+ ``` 
 
 #### Parameters
 Parameter | Description | Required | Default
@@ -69,6 +97,7 @@ Parameter | Description | Required | Default
 `resourceClasses`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false|
 `prettyPrint`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false|`TRUE`
 `openapiFilePath`|path to openapi file to be merged with resolved specification, see [config](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false|
+`configurationFilePath`|path to swagger config file to be merged with resolved specification, see [config](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration)|false|
 `filterClass`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false|
 `readerClass`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false|
 `scannerClass`|see [configuration property](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration-properties)|false|
@@ -80,3 +109,4 @@ Parameter | Description | Required | Default
 
 ***
 
+Since version 2.0.8, configurationFilePath parameter is available, allowing to specify a path to a [swagger configuration file](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Integration-and-Configuration#configuration); If single maven configuration parameters (e.g. `prettyPrint`) are also defined, these will overwrite any value set in configuration file; the same applies to `openapiFilePath` which takes precedence over `openAPI` field in configuration file.

modules/swagger-maven-plugin/src/main/java/io/swagger/v3/plugin/maven/SwaggerMojo.java

@@ -15,6 +15,7 @@
 import org.apache.maven.plugins.annotations.Parameter;
 import org.apache.maven.plugins.annotations.ResolutionScope;
 import org.apache.maven.project.MavenProject;
+import org.codehaus.plexus.util.FileUtils;
 import org.codehaus.plexus.util.StringUtils;
 
 import java.io.File;
@@ -23,9 +24,10 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.Paths;
-import java.util.Collection;
-import java.util.LinkedHashSet;
-import java.util.Set;
+import java.util.*;
+import java.util.function.BiFunction;
+
+import static java.lang.String.format;
 
 @Mojo(
     name = "resolve",
@@ -36,17 +38,17 @@
 )
 public class SwaggerMojo extends AbstractMojo {
 
-    public enum Format {JSON, YAML, JSONANDYAML};
+    public enum Format {JSON, YAML, JSONANDYAML}
 
-    public void execute() throws MojoExecutionException, MojoFailureException
-    {
+    @Override
+    public void execute() throws MojoExecutionException, MojoFailureException {
         if (skip) {
             getLog().info( "Skipping OpenAPI specification resolution" );
             return;
         }
         getLog().info( "Resolving OpenAPI specification.." );
 
-        if(project !=null) {
+        if (project != null) {
             String pEnc = project.getProperties().getProperty("project.build.sourceEncoding");
             if (StringUtils.isNotBlank(pEnc)) {
                 projectEncoding = pEnc;
@@ -56,43 +58,18 @@ public void execute() throws MojoExecutionException, MojoFailureException
             encoding = projectEncoding;
         }
 
-        OpenAPI openAPIInput = null;
-        try {
-            if (StringUtils.isNotBlank(openapiFilePath)) {
-                Path openapiPath = Paths.get(openapiFilePath);
-                if (openapiPath.toFile().exists() && openapiPath.toFile().isFile()) {
-                    String openapiFileContent = new String(Files.readAllBytes(openapiPath), encoding);
-                    if (StringUtils.isNotBlank(openapiFileContent)) {
-                        try {
-                            openAPIInput = Json.mapper().readValue(openapiFileContent, OpenAPI.class);
-                        } catch (Exception e) {
-                            try {
-                                openAPIInput = Yaml.mapper().readValue(openapiFileContent, OpenAPI.class);
-                            } catch (Exception e1) {
-                                getLog().error( "Error reading/deserializing openapi file" , e);
-                                throw new MojoFailureException(e.getMessage(), e);
-                            }
-                        }
-                    }
-                }
-            }
-        } catch (Exception e) {
-            getLog().error( "Error reading/deserializing openapi file" , e);
-            throw new MojoFailureException(e.getMessage(), e);
-        }
+        // read swagger configuration if one was provided
+        Optional<SwaggerConfiguration> swaggerConfiguration =
+                readStructuredDataFromFile(configurationFilePath, SwaggerConfiguration.class, "configurationFilePath");
+
+        // read openApi config, if one was provided
+        Optional<OpenAPI> openAPIInput =
+                readStructuredDataFromFile(openapiFilePath, OpenAPI.class, "openapiFilePath");
+
+        config = mergeConfig(openAPIInput.orElse(null), swaggerConfiguration.orElse(new SwaggerConfiguration()));
+
+        setDefaultsIfMissing(config);
 
-        SwaggerConfiguration config = new SwaggerConfiguration()
-                .filterClass(filterClass)
-                .ignoredRoutes(ignoredRoutes)
-                .prettyPrint(prettyPrint)
-                .readAllResources(readAllResources)
-                .readerClass(readerClass)
-                .scannerClass(scannerClass)
-                .resourceClasses(resourceClasses)
-                .openAPI(openAPIInput)
-                .resourcePackages(resourcePackages)
-                .objectMapperProcessorClass(objectMapperProcessorClass)
-                .modelConverterClasses(modelConverterClasses);
         try {
             GenericOpenApiContextBuilder builder = new JaxrsOpenApiContextBuilder()
                     .openApiConfiguration(config);
@@ -147,6 +124,172 @@ public void execute() throws MojoExecutionException, MojoFailureException
         }
     }
 
+    private void setDefaultsIfMissing(SwaggerConfiguration config) {
+
+        if (prettyPrint == null) {
+            prettyPrint = Boolean.FALSE;
+        }
+        if (readAllResources == null) {
+            readAllResources = Boolean.TRUE;
+        }
+        if (config.isPrettyPrint() == null) {
+            config.prettyPrint(prettyPrint);
+        }
+        if (config.isReadAllResources() == null) {
+            config.readAllResources(readAllResources);
+        }
+    }
+
+    /**
+     * Read the content of given file as either json or yaml and maps it to given class
+     *
+     * @param filePath    to read content from
+     * @param outputClass to map to
+     * @param configName  for logging, what user config will be read
+     * @param <T>         mapped type
+     * @return empty optional if not path was given or the file was empty, read instance otherwis
+     * @throws MojoFailureException if given path is not file, could not be read or is not proper json or yaml
+     */
+    private <T> Optional<T> readStructuredDataFromFile(String filePath, Class<T> outputClass, String configName)
+            throws MojoFailureException {
+        try {
+            // ignore if config is not provided
+            if (StringUtils.isBlank(filePath)) {
+                return Optional.empty();
+            }
+
+            Path pathObj = Paths.get(filePath);
+
+            // if file does not exist or is not an actual file, finish with error
+            if (!pathObj.toFile().exists() || !pathObj.toFile().isFile()) {
+                throw new IllegalArgumentException(
+                        format("passed path does not exist or is not a file: '%s'", filePath));
+            }
+
+            String fileContent = new String(Files.readAllBytes(pathObj), encoding);
+
+            // if provided file is empty, log warning and finish
+            if (StringUtils.isBlank(fileContent)) {
+                getLog().warn(format("It seems that file '%s' defined in config %s is empty",
+                        pathObj.toString(), configName));
+                return Optional.empty();
+            }
+
+            // get mappers in the order based on file extension
+            List<BiFunction<String, Class<T>, T>> mappers = getSortedMappers(pathObj);
+
+            T instance = null;
+            Throwable caughtEx = null;
+
+            // iterate through mappers and see if one is able to parse
+            for (BiFunction<String, Class<T>, T> mapper : mappers) {
+                try {
+                    instance = mapper.apply(fileContent, outputClass);
+                    break;
+                } catch (Exception e) {
+                    caughtEx = e;
+                }
+            }
+
+            // if no mapper could read the content correctly, finish with error
+            if (instance == null) {
+                if (caughtEx == null) {
+                    caughtEx = new IllegalStateException("undefined state");
+                }
+                getLog().error(format("Could not read file '%s' for config %s", pathObj.toString(), configName), caughtEx);
+                throw new IllegalStateException(caughtEx.getMessage(), caughtEx);
+            }
+
+            return Optional.of(instance);
+        } catch (Exception e) {
+            getLog().error(format("Error reading/deserializing config %s file", configName), e);
+            throw new MojoFailureException(e.getMessage(), e);
+        }
+    }
+
+    /**
+     * Get sorted list of mappers based on given filename.
+     * <p>
+     * Will sort the 2 supported mappers: json and yaml based on what file extension is used.
+     *
+     * @param pathObj to get extension from.
+     * @param <T>     mapped type
+     * @return list of mappers
+     */
+    private <T> List<BiFunction<String, Class<T>, T>> getSortedMappers(Path pathObj) {
+        String ext = FileUtils.extension(pathObj.toString());
+        boolean yamlPreferred = false;
+        if (ext.equalsIgnoreCase("yaml") || ext.equalsIgnoreCase("yml")) {
+            yamlPreferred = true;
+        }
+
+        List<BiFunction<String, Class<T>, T>> list = new ArrayList<>(2);
+
+        list.add((content, typeClass) -> {
+            try {
+                return Json.mapper().readValue(content, typeClass);
+            } catch (IOException e) {
+                throw new IllegalStateException(e);
+            }
+        });
+        list.add((content, typeClass) -> {
+            try {
+                return Yaml.mapper().readValue(content, typeClass);
+            } catch (IOException e) {
+                throw new IllegalStateException(e);
+            }
+        });
+
+        if (yamlPreferred) {
+            Collections.reverse(list);
+        }
+
+        return Collections.unmodifiableList(list);
+    }
+
+    private SwaggerConfiguration mergeConfig(OpenAPI openAPIInput, SwaggerConfiguration config) {
+        // overwrite all settings provided by other maven config
+        if (StringUtils.isNotBlank(filterClass)) {
+            config.filterClass(filterClass);
+        }
+        if (isCollectionNotBlank(ignoredRoutes)) {
+            config.ignoredRoutes(ignoredRoutes);
+        }
+        if (prettyPrint != null) {
+            config.prettyPrint(prettyPrint);
+        }
+        if (readAllResources != null) {
+            config.readAllResources(readAllResources);
+        }
+        if (StringUtils.isNotBlank(readerClass)) {
+            config.readerClass(readerClass);
+        }
+        if (StringUtils.isNotBlank(scannerClass)) {
+            config.scannerClass(scannerClass);
+        }
+        if (isCollectionNotBlank(resourceClasses)) {
+            config.resourceClasses(resourceClasses);
+        }
+        if (openAPIInput != null) {
+            config.openAPI(openAPIInput);
+        }
+        if (isCollectionNotBlank(resourcePackages)) {
+            config.resourcePackages(resourcePackages);
+        }
+        if (StringUtils.isNotBlank(objectMapperProcessorClass)) {
+            config.objectMapperProcessorClass(objectMapperProcessorClass);
+        }
+        if (isCollectionNotBlank(modelConverterClasses)) {
+            config.modelConverterClasses(modelConverterClasses);
+        }
+
+        return config;
+    }
+
+    private boolean isCollectionNotBlank(Collection<?> collection) {
+        return collection != null && !collection.isEmpty();
+    }
+
     @Parameter( property = "resolve.outputFileName", defaultValue = "openapi")
     private String outputFileName = "openapi";
 
@@ -173,10 +316,10 @@ public void execute() throws MojoExecutionException, MojoFailureException
      */
     @Parameter( property = "resolve.objectMapperProcessorClass" )
     private String objectMapperProcessorClass;
-    @Parameter( property = "resolve.prettyPrint" )
-    private Boolean prettyPrint = false;
-    @Parameter( property = "resolve.readAllResources" )
-    private Boolean readAllResources = Boolean.TRUE;
+    @Parameter(property = "resolve.prettyPrint")
+    private Boolean prettyPrint;
+    @Parameter(property = "resolve.readAllResources")
+    private Boolean readAllResources;
     @Parameter( property = "resolve.ignoredRoutes" )
     private Collection<String> ignoredRoutes;
     /**
@@ -191,19 +334,38 @@ public void execute() throws MojoExecutionException, MojoFailureException
     @Parameter( property = "resolve.openapiFilePath")
     private String openapiFilePath;
 
+    /**
+     * @since 2.0.8
+     */
+    @Parameter(property = "resolve.configurationFilePath")
+    private String configurationFilePath;
+
     @Parameter(defaultValue = "${project}", readonly = true)
     private MavenProject project;
 
     @Parameter( property = "resolve.encoding" )
     private String encoding;
 
     private String projectEncoding = "UTF-8";
+    private SwaggerConfiguration config;
 
     public String getOutputPath() {
         return outputPath;
     }
+
     public String getOpenapiFilePath() {
         return openapiFilePath;
     }
 
+    String getConfigurationFilePath() {
+        return configurationFilePath;
+    }
+
+    void setContextId(String contextId) {
+        this.contextId = contextId;
+    }
+
+    SwaggerConfiguration getInternalConfiguration() {
+        return config;
+    }
 }