improve parser error handling

Author: hauner

src/main/kotlin/io/openapiprocessor/core/parser/OpenApi.kt

@@ -26,6 +26,8 @@ interface OpenApi {
     fun getPaths(): Map<String, Path>
 
     fun getRefResolver(): RefResolver
+
     fun printWarnings()
+    fun hasWarnings(): Boolean
 
 }

src/main/kotlin/io/openapiprocessor/core/parser/ParserException.kt

@@ -0,0 +1,8 @@
+/*
+ * Copyright 2021 https://github.com/openapi-processor/openapi-processor-core
+ * PDX-License-Identifier: Apache-2.0
+ */
+
+package io.openapiprocessor.core.parser
+
+class ParserException(ex: Exception) : RuntimeException(ex)

src/main/kotlin/io/openapiprocessor/core/parser/openapi4j/OpenApi.kt

@@ -9,6 +9,8 @@ import io.openapiprocessor.core.parser.OpenApi as ParserOpenApi
 import io.openapiprocessor.core.parser.Path as ParserPath
 import io.openapiprocessor.core.parser.RefResolver as ParserRefResolver
 import org.openapi4j.core.validation.ValidationResults
+import org.slf4j.Logger
+import org.slf4j.LoggerFactory
 import org.openapi4j.parser.model.v3.OpenApi3 as O4jOpenApi
 import org.openapi4j.parser.model.v3.Path as O4jPath
 
@@ -19,6 +21,8 @@ class OpenApi(
     private val api: O4jOpenApi,
     private val validations: ValidationResults,
 ): ParserOpenApi {
+    private val log: Logger = LoggerFactory.getLogger(this.javaClass.name)
+
     private val refResolver: RefResolverNative = RefResolverNative(api)
 
     override fun getPaths(): Map<String, ParserPath> {
@@ -39,7 +43,14 @@ class OpenApi(
     override fun getRefResolver(): ParserRefResolver = RefResolver (api)
 
     override fun printWarnings() {
-        // already prints warnings
+        validations.items()
+            .forEach {
+                log.warn("{} - {} ({}}", it.severity(), it.message(), it.code())
+            }
+    }
+
+    override fun hasWarnings(): Boolean {
+        return validations.items().isNotEmpty()
     }
 
 }

src/main/kotlin/io/openapiprocessor/core/parser/openapi4j/Parser.kt

@@ -16,21 +16,41 @@
 
 package io.openapiprocessor.core.parser.openapi4j
 
+import io.openapiprocessor.core.parser.ParserException
 import io.openapiprocessor.core.support.toURL
+import org.openapi4j.core.exception.ResolutionException
+import org.openapi4j.core.validation.ValidationException
 import io.openapiprocessor.core.parser.OpenApi as ParserOpenApi
 import org.openapi4j.parser.OpenApi3Parser
 import org.openapi4j.parser.validation.v3.OpenApi3Validator
+import org.slf4j.Logger
+import org.slf4j.LoggerFactory
 
 /**
  * openapi4j parser.
  *
  * @author Martin Hauner
  */
 open class Parser {
+    private val log: Logger = LoggerFactory.getLogger(this.javaClass.name)
 
     fun parse(apiPath: String): ParserOpenApi {
+        try {
+            return run(apiPath)
+        } catch (ex: ResolutionException) {
+            log.error("can't read OpenAPI description!")
+            log.error(ex.message)
+            throw ParserException(ex)
+        } catch (ex: ValidationException) {
+            log.error("failed to parse OpenAPI description!")
+            log.error(ex.results().toString())
+            throw ParserException(ex)
+        }
+    }
+
+    private fun run(apiPath: String): ParserOpenApi {
         val api = OpenApi3Parser()
-            .parse(toURL (apiPath), true)
+            .parse(toURL(apiPath), true)
 
         val results = OpenApi3Validator
             .instance()

src/main/kotlin/io/openapiprocessor/core/parser/swagger/FailedException.kt

@@ -0,0 +1,8 @@
+/*
+ * Copyright 2021 https://github.com/openapi-processor/openapi-processor-core
+ * PDX-License-Identifier: Apache-2.0
+ */
+
+package io.openapiprocessor.core.parser.swagger
+
+class FailedException : RuntimeException()

src/main/kotlin/io/openapiprocessor/core/parser/swagger/OpenApi.kt

@@ -45,17 +45,13 @@ class OpenApi(private val result: SwaggerParseResult): ParserOpenApi {
     override fun getRefResolver(): ParserRefResolver = RefResolver (result.openAPI)
 
     override fun printWarnings() {
-        print (result.messages)
-    }
-
-    private fun print (warnings: List<String>) {
-        if (warnings.isEmpty()) {
-            return
-        }
-
-        warnings.forEach {
+        result.messages?.forEach {
             log.warn(it)
         }
     }
 
+    override fun hasWarnings(): Boolean {
+        return result.messages.isNotEmpty()
+    }
+
 }

src/main/kotlin/io/openapiprocessor/core/parser/swagger/Parser.kt

@@ -16,10 +16,12 @@
 
 package io.openapiprocessor.core.parser.swagger
 
+import io.openapiprocessor.core.parser.ParserException
 import io.openapiprocessor.core.support.toURL
 import io.swagger.v3.parser.OpenAPIV3Parser
 import io.swagger.v3.parser.core.models.ParseOptions
-import io.swagger.v3.parser.core.models.SwaggerParseResult
+import org.slf4j.Logger
+import org.slf4j.LoggerFactory
 import io.openapiprocessor.core.parser.OpenApi as ParserOpenApi
 
 const val SCHEME_RESOURCE = "resource:"
@@ -30,15 +32,49 @@ const val SCHEME_RESOURCE = "resource:"
  * @author Martin Hauner
  */
 open class Parser {
+    private val log: Logger = LoggerFactory.getLogger(this.javaClass.name)
+
+    private enum class Source {URL, STRING}
 
     fun parse(apiPath: String): ParserOpenApi {
+        try {
+            return run(apiPath, Source.URL)
+        } catch (ex: Exception) {
+            log.error("can't read OpenAPI description!")
+            throw ParserException(ex)
+        }
+    }
+
+    /** test only */
+    fun parseString(api: String): ParserOpenApi {
+        try {
+            return run(api, Source.STRING)
+        } catch (ex: Exception) {
+            throw ParserException(ex)
+        }
+    }
+
+    private fun run(api: String, source: Source): ParserOpenApi {
         val opts = ParseOptions()
         // loads $refs to other files into #/components/schema and replaces the $refs to the
         // external files with $refs to #/components/schema.
         opts.isResolve = true
 
-        val result: SwaggerParseResult = OpenAPIV3Parser()
-                  .readLocation(preparePath(apiPath), null, opts)
+        val result = when(source) {
+            Source.URL -> {
+                OpenAPIV3Parser().readLocation(preparePath(api), null, opts)
+            }
+            Source.STRING -> {
+                OpenAPIV3Parser().readContents(api, null, opts)
+            }
+        }
+
+        if (result.openAPI == null) {
+            result.messages?.forEach {
+                log.error(it)
+            }
+            throw FailedException()
+        }
 
         return OpenApi(result)
     }

src/test/kotlin/io/openapiprocessor/core/parser/openapi4j/ParserSpec.kt

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2021 https://github.com/openapi-processor/openapi-processor-core
+ * PDX-License-Identifier: Apache-2.0
+ */
+
+package io.openapiprocessor.core.parser.openapi4j
+
+import io.kotest.assertions.throwables.shouldThrow
+import io.kotest.core.spec.style.StringSpec
+import io.openapiprocessor.core.parser.ParserException
+import io.openapiprocessor.test.stream.Memory
+
+class ParserSpec : StringSpec({
+
+    "catch parser resource exception" {
+        val parser = Parser()
+
+        shouldThrow<ParserException> {
+            parser.parse("memory:openapi.yaml")
+        }
+    }
+
+    "catch parser validation exception" {
+        Memory.add("openapi.yaml", """
+            openapi: 3.0.3
+            info:
+              title: missing path
+              version: '1.0'
+        """.trimIndent()
+        )
+
+        val parser = Parser()
+
+        shouldThrow<ParserException> {
+            parser.parse("memory:openapi.yaml")
+        }
+    }
+
+    afterEach {
+        Memory.clear()
+    }
+
+})
+

src/test/kotlin/io/openapiprocessor/core/parser/swagger/ParserSpec.kt

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2021 https://github.com/openapi-processor/openapi-processor-core
+ * PDX-License-Identifier: Apache-2.0
+ */
+
+package io.openapiprocessor.core.parser.swagger
+
+import io.kotest.assertions.throwables.shouldThrow
+import io.kotest.core.spec.style.StringSpec
+import io.kotest.matchers.shouldBe
+import io.openapiprocessor.core.parser.ParserException
+
+class ParserSpec : StringSpec ({
+
+    "catch parser resource exception" {
+        val parser = Parser()
+
+        shouldThrow<ParserException> {
+            parser.parse("openapi.yaml")
+        }
+    }
+
+    "has warning messages" {
+        val parser = Parser()
+
+        val api = parser.parseString("""
+            openapi: 3.0.3
+            info:
+              title: missing path
+              version: '1.0'
+              
+              """.trimIndent())
+
+        api.hasWarnings() shouldBe true
+    }
+
+})