[Fix 177]: Throw exception when spec version is not recognized by reader (#181)

Throwing OpenApiUnsupportedSpecVersionException when spec version is not recognized in Reader

Author: scott-lin

src/Microsoft.OpenApi.Readers/Exceptions/OpenApiReaderException.cs

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. 
+
+using System;
+
+namespace Microsoft.OpenApi.Readers.Exceptions
+{
+    /// <summary>
+    /// Defines an exception indicating OpenAPI Reader encountered an issue while reading.
+    /// </summary>
+    [Serializable]
+    public class OpenApiReaderException : Exception
+    {
+        /// <summary>
+        /// Initializes the <see cref="OpenApiReaderException"/> class.
+        /// </summary>
+        public OpenApiReaderException() { }
+
+        /// <summary>
+        /// Initializes the <see cref="OpenApiReaderException"/> class with a custom message.
+        /// </summary>
+        /// <param name="message">Plain text error message for this exception.</param>
+        public OpenApiReaderException(string message) : base(message) { }
+
+        /// <summary>
+        /// Initializes the <see cref="OpenApiReaderException"/> class with a custom message and inner exception.
+        /// </summary>
+        /// <param name="message">Plain text error message for this exception.</param>
+        /// <param name="innerException">Inner exception that caused this exception to be thrown.</param>
+        public OpenApiReaderException(string message, Exception innerException) : base(message, innerException) { }
+    }
+}

src/Microsoft.OpenApi.Readers/Exceptions/OpenApiUnsupportedSpecVersionException.cs

@@ -0,0 +1,54 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. 
+
+using System;
+using System.Globalization;
+
+namespace Microsoft.OpenApi.Readers.Exceptions
+{
+    /// <summary>
+    /// Defines an exception indicating OpenAPI Reader encountered an unsupported specification version while reading.
+    /// </summary>
+    [Serializable]
+    public class OpenApiUnsupportedSpecVersionException : OpenApiReaderException
+    {
+        const string messagePattern = "OpenAPI specification version {0} is not supported.";
+
+        /// <summary>
+        /// Initializes the <see cref="OpenApiUnsupportedSpecVersionException"/> class with a specification version.
+        /// </summary>
+        /// <param name="specificationVersion">Version that caused this exception to be thrown.</param>
+        public OpenApiUnsupportedSpecVersionException(string specificationVersion)
+            : base(string.Format(CultureInfo.InvariantCulture, messagePattern, specificationVersion))
+        {
+            if (string.IsNullOrWhiteSpace(specificationVersion))
+            {
+                throw new ArgumentException("Value cannot be null or white space.", nameof(specificationVersion));
+            }
+
+            this.SpecificationVersion = specificationVersion;
+        }
+
+        /// <summary>
+        /// Initializes the <see cref="OpenApiUnsupportedSpecVersionException"/> class with a specification version and
+        /// inner exception.
+        /// </summary>
+        /// <param name="specificationVersion">Version that caused this exception to be thrown.</param>
+        /// <param name="innerException">Inner exception that caused this exception to be thrown.</param>
+        public OpenApiUnsupportedSpecVersionException(string specificationVersion, Exception innerException)
+            : base(string.Format(CultureInfo.InvariantCulture, messagePattern, specificationVersion), innerException)
+        {
+            if (string.IsNullOrWhiteSpace(specificationVersion))
+            {
+                throw new ArgumentException("Value cannot be null or white space.", nameof(specificationVersion));
+            }
+
+            this.SpecificationVersion = specificationVersion;
+        }
+
+        /// <summary>
+        /// The unsupported specification version.
+        /// </summary>
+        public string SpecificationVersion { get; }
+    }
+}

src/Microsoft.OpenApi.Readers/Microsoft.OpenApi.Readers.csproj

@@ -10,7 +10,7 @@
         <Company>Microsoft</Company>
         <Title>Microsoft.OpenApi.Readers</Title>
         <PackageId>Microsoft.OpenApi.Readers</PackageId>
-        <Version>1.0.0-beta010</Version>
+        <Version>1.0.0-beta011</Version>
         <Description>OpenAPI.NET Readers for JSON and YAML documents</Description>
         <Copyright>© Microsoft Corporation. All rights reserved.</Copyright>
         <PackageTags>OpenAPI .NET</PackageTags>

src/Microsoft.OpenApi.Readers/ParsingContext.cs

@@ -6,6 +6,7 @@
 using System.Linq;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi.Readers.Exceptions;
 using Microsoft.OpenApi.Readers.Interface;
 using Microsoft.OpenApi.Readers.ParseNodes;
 using Microsoft.OpenApi.Readers.V2;
@@ -41,26 +42,24 @@ internal OpenApiDocument Parse(YamlDocument yamlDocument, OpenApiDiagnostic diag
 
             OpenApiDocument doc;
 
-            if (inputVersion == "2.0")
+            switch (inputVersion)
             {
-                VersionService = new OpenApiV2VersionService();
-                doc = this.VersionService.LoadDocument(this.RootNode);
-                diagnostic.SpecificationVersion = OpenApiSpecVersion.OpenApi2_0;
-            }
-            else if (inputVersion.StartsWith("3.0."))
-            {
-                this.VersionService = new OpenApiV3VersionService();
-                doc = this.VersionService.LoadDocument(this.RootNode);
-                diagnostic.SpecificationVersion = OpenApiSpecVersion.OpenApi3_0;
-            }
-            else
-            {
-                // If version number is not recognizable,
-                // our best effort will try to deserialize the document to V3.
-                this.VersionService = new OpenApiV3VersionService();
-                doc = this.VersionService.LoadDocument(this.RootNode);
-                diagnostic.SpecificationVersion = OpenApiSpecVersion.OpenApi3_0;
+                case string version when version == "2.0":
+                    VersionService = new OpenApiV2VersionService();
+                    doc = this.VersionService.LoadDocument(this.RootNode);
+                    diagnostic.SpecificationVersion = OpenApiSpecVersion.OpenApi2_0;
+                    break;
+
+                case string version when version.StartsWith("3.0"):
+                    this.VersionService = new OpenApiV3VersionService();
+                    doc = this.VersionService.LoadDocument(this.RootNode);
+                    diagnostic.SpecificationVersion = OpenApiSpecVersion.OpenApi3_0;
+                    break;
+
+                default:
+                    throw new OpenApiUnsupportedSpecVersionException(inputVersion);
             }
+
             return doc;
         }
 
@@ -81,7 +80,7 @@ private static string GetVersion(RootNode rootNode)
             return versionNode?.GetScalarValue();
         }
 
-        private void ComputeTags(List<OpenApiTag> tags, Func<MapNode,OpenApiTag> loadTag )
+        private void ComputeTags(List<OpenApiTag> tags, Func<MapNode, OpenApiTag> loadTag)
         {
             // Precompute the tags array so that each tag reference does not require a new deserialization.
             var tagListPointer = new JsonPointer("#/tags");

src/Microsoft.OpenApi/Microsoft.OpenApi.csproj

@@ -10,7 +10,7 @@
         <Company>Microsoft</Company>
         <Title>Microsoft.OpenApi</Title>
         <PackageId>Microsoft.OpenApi</PackageId>
-        <Version>1.0.0-beta010</Version>
+        <Version>1.0.0-beta011</Version>
         <Description>.NET models with JSON and YAML writers for OpenAPI specification</Description>
         <Copyright>© Microsoft Corporation. All rights reserved.</Copyright>
         <PackageTags>OpenAPI .NET</PackageTags>

test/Microsoft.OpenApi.Readers.Tests/Microsoft.OpenApi.Readers.Tests.csproj

@@ -13,6 +13,9 @@
         <AssemblyOriginatorKeyFile>..\..\src\Microsoft.OpenApi.snk</AssemblyOriginatorKeyFile>
     </PropertyGroup>
     <ItemGroup>
+      <EmbeddedResource Include="OpenApiReaderTests\Samples\unsupported.v1.yaml">
+        <CopyToOutputDirectory>Never</CopyToOutputDirectory>
+      </EmbeddedResource>
       <EmbeddedResource Include="ReferenceService\Samples\multipleReferences.v2.yaml">
         <CopyToOutputDirectory>Never</CopyToOutputDirectory>
       </EmbeddedResource>

test/Microsoft.OpenApi.Readers.Tests/OpenApiReaderTests/Samples/unsupported.v1.yaml

@@ -0,0 +1,8 @@
+swagger: 1.0.0
+info: 
+  title: This is a simple example
+  version: 1.0.0
+host: example.org
+basePath: /api
+schemes: ["http", "https"]
+paths: {}

test/Microsoft.OpenApi.Readers.Tests/OpenApiReaderTests/UnsupportedSpecVersionTests.cs

@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. 
+
+using FluentAssertions;
+using Microsoft.OpenApi.Readers.Exceptions;
+using Xunit;
+
+namespace Microsoft.OpenApi.Readers.Tests.OpenApiReaderTests
+{
+    [Collection("DefaultSettings")]
+    public class UnsupportedSpecVersionTests
+    {
+        [Fact]
+        public void ThrowOpenApiUnsupportedSpecVersionException()
+        {
+            using (var stream = Resources.GetStream("OpenApiReaderTests/Samples/unsupported.v1.yaml"))
+            {
+                try
+                {
+                    new OpenApiStreamReader().Read(stream, out var diagnostic);
+                }
+                catch (OpenApiUnsupportedSpecVersionException exception)
+                {
+                    exception.SpecificationVersion.Should().Be("1.0.0");
+                }                
+            }
+        }
+    }
+}