OpenAPIWorkspace

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "workbench.colorCustomizations": {
+        "activityBar.background": "#03323C",
+        "titleBar.activeBackground": "#054754",
+        "titleBar.activeForeground": "#F0FCFE"
+    }
+}

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

@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. 
+
+using System;
+using System.IO;
+using System.Threading.Tasks;
+using Microsoft.OpenApi.Models;
+
+namespace Microsoft.OpenApi.Readers.Interface
+{
+    /// <summary>
+    /// Interface for service that translates a URI into a stream that can be loaded by a Reader
+    /// </summary>
+    public interface IStreamLoader
+    {
+        /// <summary>
+        /// Use Uri to locate data and convert into an input object.
+        /// </summary>
+        /// <param name="uri">Identifier of some source of an OpenAPI Description</param>
+        /// <returns>A data objext that can be processed by a reader to generate an <see cref="OpenApiDocument"/></returns>
+        Task<Stream> LoadAsync(Uri uri);
+
+        /// <summary>
+        /// Use Uri to locate data and convert into an input object.
+        /// </summary>
+        /// <param name="uri"></param>
+        /// <returns></returns>
+        Stream Load(Uri uri);
+    }
+}

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

@@ -1,10 +1,10 @@
 <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
-        <TargetFrameworks>net46; netstandard2.0</TargetFrameworks>
+        <TargetFrameworks>netstandard2.0</TargetFrameworks>
         <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
         <PackageIconUrl>http://go.microsoft.com/fwlink/?LinkID=288890</PackageIconUrl>
         <PackageProjectUrl>https://github.com/Microsoft/OpenAPI.NET</PackageProjectUrl>
-        <PackageLicenseUrl>https://raw.githubusercontent.com/Microsoft/OpenAPI.NET/master/LICENSE</PackageLicenseUrl>
+        <PackageLicenseExpression>MIT</PackageLicenseExpression>
         <PackageRequireLicenseAcceptance>true</PackageRequireLicenseAcceptance>
         <Authors>Microsoft</Authors>
         <Company>Microsoft</Company>
@@ -26,7 +26,7 @@
     </PropertyGroup>
 
     <ItemGroup>
-        <PackageReference Include="SharpYaml" Version="1.6.5" />
+        <PackageReference Include="SharpYaml" Version="1.6.6" />
     </ItemGroup>
 
     <ItemGroup>

src/Microsoft.OpenApi.Readers/OpenApiReaderSettings.cs

@@ -3,10 +3,13 @@
 
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Interfaces;
+using Microsoft.OpenApi.Readers.Interface;
 using Microsoft.OpenApi.Readers.ParseNodes;
+using Microsoft.OpenApi.Readers.Services;
 using Microsoft.OpenApi.Validations;
 using System;
 using System.Collections.Generic;
+using System.IO;
 using System.Linq;
 using System.Text;
 using System.Threading.Tasks;
@@ -56,5 +59,13 @@ public class OpenApiReaderSettings
         /// URL where relative references should be resolved from if the description does not contain Server definitions
         /// </summary>
         public Uri BaseUrl { get; set; }
+
+        /// <summary>
+        /// Function used to provide an alternative loader for accessing external references.  
+        /// </summary>
+        /// <remarks>
+        /// Default loader will attempt to dereference http(s) urls and file urls.
+        /// </remarks>
+        public IStreamLoader CustomExternalLoader { get; set; }
     }
 }

src/Microsoft.OpenApi.Readers/OpenApiStreamReader.cs

@@ -2,6 +2,7 @@
 // Licensed under the MIT license. 
 
 using System.IO;
+using System.Threading.Tasks;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Readers.Interface;
@@ -38,14 +39,40 @@ public OpenApiDocument Read(Stream input, out OpenApiDiagnostic diagnostic)
             }
         }
 
+        /// <summary>
+        /// Reads the stream input and parses it into an Open API document.
+        /// </summary>
+        /// <param name="input">Stream containing OpenAPI description to parse.</param>
+        /// <returns>Instance result containing newly created OpenApiDocument and diagnostics object from the process</returns>
+        public async Task<ReadResult> ReadAsync(Stream input)
+        {
+            MemoryStream bufferedStream;
+            if (input is MemoryStream)
+            {
+                bufferedStream = (MemoryStream)input;
+            } 
+            else 
+            {
+                // Buffer stream so that OpenApiTextReaderReader can process it synchronously
+                // YamlDocument doesn't support async reading.
+                bufferedStream = new MemoryStream();
+                await input.CopyToAsync(bufferedStream);
+                bufferedStream.Position = 0;
+            }
+
+            var reader = new StreamReader(bufferedStream);
+
+            return await new OpenApiTextReaderReader(_settings).ReadAsync(reader);
+        }
+
         /// <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
+        public T ReadFragment<T>(Stream input, OpenApiSpecVersion version, out OpenApiDiagnostic diagnostic) where T : IOpenApiReferenceable
         {
             using (var reader = new StreamReader(input))
             {

src/Microsoft.OpenApi.Readers/OpenApiTextReaderReader.cs

@@ -3,6 +3,7 @@
 
 using System.IO;
 using System.Linq;
+using System.Threading.Tasks;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Readers.Interface;
@@ -51,6 +52,36 @@ public OpenApiDocument Read(TextReader input, out OpenApiDiagnostic diagnostic)
 
             return new OpenApiYamlDocumentReader(this._settings).Read(yamlDocument, out diagnostic);
         }
+
+        /// <summary>
+        /// Reads the content of the TextReader.  If there are references to external documents then they will be read asynchronously.
+        /// </summary>
+        /// <param name="input">TextReader containing OpenAPI description to parse.</param>
+        /// <returns>A ReadResult instance that contains the resulting OpenApiDocument and a diagnostics instance.</returns>
+        public async Task<ReadResult> ReadAsync(TextReader input)
+        {
+            YamlDocument yamlDocument;
+
+            // Parse the YAML/JSON text in the TextReader into the YamlDocument
+            try
+            {
+                yamlDocument = LoadYamlDocument(input);
+            }
+            catch (YamlException ex)
+            {
+                var diagnostic = new OpenApiDiagnostic();
+                diagnostic.Errors.Add(new OpenApiError($"#line={ex.Start.Line}", ex.Message));
+                return new ReadResult
+                {
+                    OpenApiDocument = null,
+                    OpenApiDiagnostic = diagnostic
+                };
+            }
+
+            return await new OpenApiYamlDocumentReader(this._settings).ReadAsync(yamlDocument);
+        }
+
+
         /// <summary>
         /// Reads the stream input and parses the fragment of an OpenAPI description into an Open API Element.
         /// </summary>

src/Microsoft.OpenApi.Readers/OpenApiYamlDocumentReader.cs

@@ -2,6 +2,9 @@
 // Licensed under the MIT license. 
 
 using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Threading.Tasks;
 using Microsoft.OpenApi.Exceptions;
 using Microsoft.OpenApi.Extensions;
 using Microsoft.OpenApi.Interfaces;
@@ -50,24 +53,43 @@ public OpenApiDocument Read(YamlDocument input, out OpenApiDiagnostic diagnostic
                 // Parse the OpenAPI Document
                 document = context.Parse(input);
 
-                // Resolve References if requested
-                switch (_settings.ReferenceResolution)
+                ResolveReferences(diagnostic, document);
+            }
+            catch (OpenApiException ex)
+            {
+                diagnostic.Errors.Add(new OpenApiError(ex));
+            }
+
+            // Validate the document
+            if (_settings.RuleSet != null && _settings.RuleSet.Rules.Count > 0)
+            {
+                var errors = document.Validate(_settings.RuleSet);
+                foreach (var item in errors)
                 {
-                    case ReferenceResolutionSetting.ResolveAllReferences:
-                        throw new ArgumentException(Properties.SRResource.CannotResolveRemoteReferencesSynchronously);
-                    case ReferenceResolutionSetting.ResolveLocalReferences:
-                        var resolver = new OpenApiReferenceResolver(document);
-                        var walker = new OpenApiWalker(resolver);
-                        walker.Walk(document);
-                        foreach (var item in resolver.Errors)
-                        {
-                            diagnostic.Errors.Add(item);
-                        }
-                        break;
-                    case ReferenceResolutionSetting.DoNotResolveReferences:
-                        break;
+                    diagnostic.Errors.Add(item);
                 }
             }
+
+            return document;
+        }
+
+        public async Task<ReadResult> ReadAsync(YamlDocument input)
+        {
+            var diagnostic = new OpenApiDiagnostic();
+            var context = new ParsingContext(diagnostic)
+            {
+                ExtensionParsers = _settings.ExtensionParsers,
+                BaseUrl = _settings.BaseUrl
+            };
+
+            OpenApiDocument document = null;
+            try
+            {
+                // Parse the OpenAPI Document
+                document = context.Parse(input);
+
+                await ResolveReferencesAsync(diagnostic, document);
+            }
             catch (OpenApiException ex)
             {
                 diagnostic.Errors.Add(new OpenApiError(ex));
@@ -83,8 +105,71 @@ public OpenApiDocument Read(YamlDocument input, out OpenApiDiagnostic diagnostic
                 }
             }
 
-            return document;
+            return new ReadResult()
+            {
+                OpenApiDocument = document,
+                OpenApiDiagnostic = diagnostic
+            };
+        }
+
+
+        private void ResolveReferences(OpenApiDiagnostic diagnostic, OpenApiDocument document)
+        {
+            // Resolve References if requested
+            switch (_settings.ReferenceResolution)
+            {
+                case ReferenceResolutionSetting.ResolveAllReferences:
+                    throw new ArgumentException("Cannot resolve all references via a synchronous call. Use ReadAsync.");
+                case ReferenceResolutionSetting.ResolveLocalReferences:
+                    var errors = document.ResolveReferences(false);
+
+                    foreach (var item in errors)
+                    {
+                        diagnostic.Errors.Add(item);
+                    }
+                    break;
+                case ReferenceResolutionSetting.DoNotResolveReferences:
+                    break;
+            }
         }
+
+        private async Task ResolveReferencesAsync(OpenApiDiagnostic diagnostic, OpenApiDocument document)
+        {
+            List<OpenApiError> errors = new List<OpenApiError>();
+
+            // Resolve References if requested
+            switch (_settings.ReferenceResolution)
+            {
+                case ReferenceResolutionSetting.ResolveAllReferences:
+
+                    // Create workspace for all documents to live in.
+                    var openApiWorkSpace = new OpenApiWorkspace();
+
+                    // Load this root document into the workspace
+                    var streamLoader = new DefaultStreamLoader();
+                    var workspaceLoader = new OpenApiWorkspaceLoader(openApiWorkSpace, _settings.CustomExternalLoader ?? streamLoader, _settings);
+                    await workspaceLoader.LoadAsync(new OpenApiReference() { ExternalResource = "/" }, document);
+
+                    // Resolve all references in all the documents loaded into the OpenApiWorkspace
+                    foreach (var doc in openApiWorkSpace.Documents)
+                    {
+                        errors.AddRange(doc.ResolveReferences(true));
+                    }
+                    break;
+                case ReferenceResolutionSetting.ResolveLocalReferences:
+                    errors.AddRange(document.ResolveReferences(false));
+                    break;
+                case ReferenceResolutionSetting.DoNotResolveReferences:
+                    break;
+            }
+
+            foreach (var item in errors)
+            {
+                diagnostic.Errors.Add(item);
+            }
+        }
+
+
         /// <summary>
         /// Reads the stream input and parses the fragment of an OpenAPI description into an Open API Element.
         /// </summary>

src/Microsoft.OpenApi.Readers/ReadResult.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. 
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+using Microsoft.OpenApi.Models;
+
+namespace Microsoft.OpenApi.Readers
+{
+    /// <summary>
+    /// Container object used for returning the result of reading an OpenAPI description.
+    /// </summary>
+    public class ReadResult
+    {
+        /// <summary>
+        /// The parsed OpenApiDocument.  Null will be returned if the document could not be parsed.
+        /// </summary>
+        public OpenApiDocument OpenApiDocument { set; get; }
+        /// <summary>
+        /// OpenApiDiagnostic contains the Errors reported while parsing
+        /// </summary>
+        public OpenApiDiagnostic OpenApiDiagnostic { set; get; }
+    }
+}