Merge pull request #312 from Microsoft/dm/release1.1

Release 1.1

Author: darrelmiller

build.cmd

@@ -1,7 +1,7 @@
 @echo off
 if "%~1"=="" goto :error
 
-SET %VERSION%=%~1
+SET VERSION=%~1
 
 Echo Building Microsoft.OpenApi
 

src/Directory.Build.props

@@ -0,0 +1,8 @@
+<Project>
+  <PropertyGroup>
+    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.0.0-*" PrivateAssets="All"/>
+  </ItemGroup>
+</Project>

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

@@ -2,14 +2,16 @@
 // Licensed under the MIT license. 
 
 using System;
+using Microsoft.OpenApi.Exceptions;
+using SharpYaml.Serialization;
 
 namespace Microsoft.OpenApi.Readers.Exceptions
 {
     /// <summary>
     /// Defines an exception indicating OpenAPI Reader encountered an issue while reading.
     /// </summary>
     [Serializable]
-    public class OpenApiReaderException : Exception
+    public class OpenApiReaderException : OpenApiException
     {
         /// <summary>
         /// Initializes the <see cref="OpenApiReaderException"/> class.
@@ -22,6 +24,18 @@ public OpenApiReaderException() { }
         /// <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 message and line, column location of error.
+        /// </summary>
+        /// <param name="message">Plain text error message for this exception.</param>
+        /// <param name="node">Parsing node where error occured</param>
+        public OpenApiReaderException(string message, YamlNode node) : base(message)
+        {
+            // This only includes line because using a char range causes tests to break due to CR/LF & LF differences
+            // See https://tools.ietf.org/html/rfc5147 for syntax
+            Pointer = $"#line={node.Start.Line}";  
+        }
+
         /// <summary>
         /// Initializes the <see cref="OpenApiReaderException"/> class with a custom message and inner exception.
         /// </summary>

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

@@ -10,9 +10,9 @@ namespace Microsoft.OpenApi.Readers.Exceptions
     /// Defines an exception indicating OpenAPI Reader encountered an unsupported specification version while reading.
     /// </summary>
     [Serializable]
-    public class OpenApiUnsupportedSpecVersionException : OpenApiReaderException
+    public class OpenApiUnsupportedSpecVersionException : Exception
     {
-        const string messagePattern = "OpenAPI specification version {0} is not supported.";
+        const string messagePattern = "OpenAPI specification version '{0}' is not supported.";
 
         /// <summary>
         /// Initializes the <see cref="OpenApiUnsupportedSpecVersionException"/> class with a specification version.
@@ -21,11 +21,6 @@ public class OpenApiUnsupportedSpecVersionException : OpenApiReaderException
         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;
         }
 
@@ -38,11 +33,6 @@ public OpenApiUnsupportedSpecVersionException(string specificationVersion)
         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;
         }
 

src/Microsoft.OpenApi.Readers/Interface/IOpenApiVersionService.cs

@@ -23,9 +23,12 @@ internal interface IOpenApiVersionService
         OpenApiReference ConvertToOpenApiReference(string reference, ReferenceType? type);
 
         /// <summary>
-        /// Function that converts a MapNode into a Tag object in a version specific way
+        /// Loads an OpenAPI Element from a document fragment
         /// </summary>
-        Func<MapNode, OpenApiTag> TagLoader { get; }
+        /// <typeparam name="T">Type of element to load</typeparam>
+        /// <param name="node">document fragment node</param>
+        /// <returns>Instance of OpenAPIElement</returns>
+        T LoadElement<T>(ParseNode node) where T : IOpenApiElement;
 
         /// <summary>
         /// Converts a generic RootNode instance into a strongly typed OpenApiDocument

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.1</Version>
+        <Version>1.1.0</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/OpenApiReaderError.cs

@@ -42,12 +42,16 @@ public class OpenApiReaderSettings
         /// <summary>
         /// Dictionary of parsers for converting extensions into strongly typed classes
         /// </summary>
-        public Dictionary<string, Func<IOpenApiAny , IOpenApiExtension>> ExtensionParsers { get; set; } = new Dictionary<string, Func<IOpenApiAny, IOpenApiExtension>>();
+        public Dictionary<string, Func<IOpenApiAny , OpenApiSpecVersion, IOpenApiExtension>> ExtensionParsers { get; set; } = new Dictionary<string, Func<IOpenApiAny, OpenApiSpecVersion, IOpenApiExtension>>();
 
         /// <summary>
         /// Rules to use for validating OpenAPI specification.  If none are provided a default set of rules are applied.
         /// </summary>
         public ValidationRuleSet RuleSet { get; set; } = ValidationRuleSet.GetDefaultRuleSet();
 
+        /// <summary>
+        /// URL where relative references should be resolved from if the description does not contain Server definitions
+        /// </summary>
+        public Uri BaseUrl { get; set; } 
     }
 }

src/Microsoft.OpenApi.Readers/OpenApiReaderSettings.cs

@@ -6,6 +6,7 @@
 using System.Linq;
 using Microsoft.OpenApi.Exceptions;
 using Microsoft.OpenApi.Extensions;
+using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Readers.Interface;
 using Microsoft.OpenApi.Readers.Services;
@@ -48,15 +49,16 @@ public OpenApiDocument Read(Stream input, out OpenApiDiagnostic diagnostic)
             {
                 yamlDocument = LoadYamlDocument(input);
             }
-            catch (SyntaxErrorException ex)
+            catch (YamlException ex)
             {
-                diagnostic.Errors.Add(new OpenApiReaderError(ex));
+                diagnostic.Errors.Add(new OpenApiError($"#char={ex.Start.Line}", ex.Message));
                 return new OpenApiDocument();
             }
 
             context = new ParsingContext
             {
-                ExtensionParsers = _settings.ExtensionParsers
+                ExtensionParsers = _settings.ExtensionParsers,
+                BaseUrl = _settings.BaseUrl
             };
 
             OpenApiDocument document = null;
@@ -102,6 +104,60 @@ public OpenApiDocument Read(Stream input, out OpenApiDiagnostic diagnostic)
             return document;
         }
 
+        /// <summary>
+        /// Reads the stream input and parses the fragment of an OpenAPI description into an Open API Element.
+        /// </summary>
+        /// <param name="input">Stream containing OpenAPI description to parse.</param>
+        /// <param name="version">Version of the OpenAPI specification that the fragment conforms to.</param>
+        /// <param name="diagnostic">Returns diagnostic object containing errors detected during parsing</param>
+        /// <returns>Instance of newly created OpenApiDocument</returns>
+        public T ReadFragment<T>(Stream input, OpenApiSpecVersion version, out OpenApiDiagnostic diagnostic) where T : IOpenApiElement
+        {
+            ParsingContext context;
+            YamlDocument yamlDocument;
+            diagnostic = new OpenApiDiagnostic();
+
+            // Parse the YAML/JSON
+            try
+            {
+                yamlDocument = LoadYamlDocument(input);
+            }
+            catch (YamlException ex)
+            {
+                diagnostic.Errors.Add(new OpenApiError($"#line={ex.Start.Line}", ex.Message));
+                return default(T);
+            }
+
+            context = new ParsingContext
+            {
+                ExtensionParsers = _settings.ExtensionParsers
+            };
+
+            IOpenApiElement element = null;
+
+            try
+            {
+                // Parse the OpenAPI element
+                element = context.ParseFragment<T>(yamlDocument, version, diagnostic);
+            }
+            catch (OpenApiException ex)
+            {
+                diagnostic.Errors.Add(new OpenApiError(ex));
+            }
+
+            // Validate the element
+            if (_settings.RuleSet != null && _settings.RuleSet.Rules.Count > 0)
+            {
+                var errors = element.Validate(_settings.RuleSet);
+                foreach (var item in errors)
+                {
+                    diagnostic.Errors.Add(item);
+                }
+            }
+
+            return (T)element;
+        }
+
         /// <summary>
         /// Helper method to turn streams into YamlDocument
         /// </summary>

src/Microsoft.OpenApi.Readers/OpenApiStreamReader.cs

@@ -2,6 +2,7 @@
 // Licensed under the MIT license. 
 
 using System.IO;
+using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Readers.Interface;
 
@@ -20,7 +21,7 @@ public class OpenApiStringReader : IOpenApiReader<string, OpenApiDiagnostic>
         /// <param name="settings"></param>
         public OpenApiStringReader(OpenApiReaderSettings settings = null)
         {
-            _settings = settings ?? new OpenApiReaderSettings(); 
+            _settings = settings ?? new OpenApiReaderSettings();
         }
 
         /// <summary>
@@ -38,5 +39,21 @@ public OpenApiDocument Read(string input, out OpenApiDiagnostic diagnostic)
                 return new OpenApiStreamReader(_settings).Read(memoryStream, out diagnostic);
             }
         }
+
+        /// <summary>
+        /// Reads the string input and parses it into an Open API element.
+        /// </summary>
+        public T ReadFragment<T>(string input, OpenApiSpecVersion version, out OpenApiDiagnostic diagnostic) where T : IOpenApiElement
+        {
+            using (var memoryStream = new MemoryStream())
+            {
+                var writer = new StreamWriter(memoryStream);
+                writer.Write(input);
+                writer.Flush();
+                memoryStream.Position = 0;
+
+                return new OpenApiStreamReader(_settings).ReadFragment<T>(memoryStream, version, out diagnostic);
+            }
+        }
     }
 }