Create dotnet commandline tool for performing conversions and inlining

Microsoft.OpenApi.sln

@@ -26,6 +26,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "test", "test", "{6357D7FD-2
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.OpenApi.SmokeTests", "test\Microsoft.OpenApi.SmokeTests\Microsoft.OpenApi.SmokeTests.csproj", "{AD79B61D-88CF-497C-9ED5-41AE3867C5AC}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Microsoft.OpenApi.Tool", "src\Microsoft.OpenApi.Tool\Microsoft.OpenApi.Tool.csproj", "{254841B5-7DAC-4D1D-A9C5-44FE5CE467BE}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -56,6 +58,10 @@ Global
 		{AD79B61D-88CF-497C-9ED5-41AE3867C5AC}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{AD79B61D-88CF-497C-9ED5-41AE3867C5AC}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{AD79B61D-88CF-497C-9ED5-41AE3867C5AC}.Release|Any CPU.Build.0 = Release|Any CPU
+		{254841B5-7DAC-4D1D-A9C5-44FE5CE467BE}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{254841B5-7DAC-4D1D-A9C5-44FE5CE467BE}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{254841B5-7DAC-4D1D-A9C5-44FE5CE467BE}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{254841B5-7DAC-4D1D-A9C5-44FE5CE467BE}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -67,6 +73,7 @@ Global
 		{AD83F991-DBF3-4251-8613-9CC54C826964} = {6357D7FD-2DE4-4900-ADB9-ABC37052040A}
 		{1ED3C2C1-E1E7-4925-B4E6-2D969C3F5237} = {6357D7FD-2DE4-4900-ADB9-ABC37052040A}
 		{AD79B61D-88CF-497C-9ED5-41AE3867C5AC} = {6357D7FD-2DE4-4900-ADB9-ABC37052040A}
+		{254841B5-7DAC-4D1D-A9C5-44FE5CE467BE} = {E546B92F-20A8-49C3-8323-4B25BB78F3E1}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {9F171EFC-0DB5-4B10-ABFA-AF48D52CC565}

build.cmd

@@ -1,5 +1,5 @@
 @echo off
-Echo Building Microsoft.OpenApi
+Echo Building Microsoft.OpenApi 
 
 SET PROJ=%~dp0src\Microsoft.OpenApi\Microsoft.OpenApi.csproj 
 dotnet build %PROJ% /t:restore /p:Configuration=Release

src/Microsoft.OpenApi.Readers/ParsingContext.cs

@@ -30,8 +30,15 @@ public class ParsingContext
         internal List<OpenApiTag> Tags { get; private set; } = new List<OpenApiTag>();
         internal Uri BaseUrl { get; set; }
 
+        /// <summary>
+        /// Diagnostic object that returns metadata about the parsing process.
+        /// </summary>
         public OpenApiDiagnostic Diagnostic { get; }
 
+        /// <summary>
+        /// Create Parsing Context
+        /// </summary>
+        /// <param name="diagnostic">Provide instance for diagnotic object for collecting and accessing information about the parsing.</param>
         public ParsingContext(OpenApiDiagnostic diagnostic)
         {
             Diagnostic = diagnostic;
@@ -41,7 +48,6 @@ public ParsingContext(OpenApiDiagnostic diagnostic)
         /// Initiates the parsing process.  Not thread safe and should only be called once on a parsing context
         /// </summary>
         /// <param name="yamlDocument">Yaml document to parse.</param>
-        /// <param name="diagnostic">Diagnostic object which will return diagnostic results of the operation.</param>
         /// <returns>An OpenApiDocument populated based on the passed yamlDocument </returns>
         internal OpenApiDocument Parse(YamlDocument yamlDocument)
         {
@@ -77,7 +83,6 @@ internal OpenApiDocument Parse(YamlDocument yamlDocument)
         /// </summary>
         /// <param name="yamlDocument"></param>
         /// <param name="version">OpenAPI version of the fragment</param>
-        /// <param name="diagnostic">Diagnostic object which will return diagnostic results of the operation.</param>
         /// <returns>An OpenApiDocument populated based on the passed yamlDocument </returns>
         internal T ParseFragment<T>(YamlDocument yamlDocument, OpenApiSpecVersion version) where T : IOpenApiElement
         {

src/Microsoft.OpenApi.Tool/Microsoft.OpenApi.Tool.csproj

@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>netcoreapp3.1</TargetFramework>
+    <PackAsTool>true</PackAsTool>
+    <ToolCommandName>openapi</ToolCommandName>
+    <PackageOutputPath>./../../artifacts</PackageOutputPath>
+    <Version>0.5.0</Version>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="System.CommandLine" Version="2.0.0-beta1.20104.2" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Microsoft.OpenApi.Readers\Microsoft.OpenApi.Readers.csproj" />
+    <ProjectReference Include="..\Microsoft.OpenApi\Microsoft.OpenApi.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Update="Microsoft.SourceLink.GitHub" Version="1.0.0" />
+  </ItemGroup>
+
+</Project>

src/Microsoft.OpenApi.Tool/OpenApiService.cs

@@ -0,0 +1,81 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Text;
+using Microsoft.OpenApi.Extensions;
+using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi.Readers;
+using Microsoft.OpenApi.Validations;
+using Microsoft.OpenApi.Writers;
+
+namespace Microsoft.OpenApi.Tool
+{
+    static class OpenApiService
+    {
+        public static void ProcessOpenApiDocument(
+            FileInfo input,
+            FileInfo output,
+            OpenApiSpecVersion version,
+            OpenApiFormat format,
+            bool inline)
+        {
+            OpenApiDocument document;
+            using (Stream stream = input.OpenRead())
+            {
+
+                document = new OpenApiStreamReader(new OpenApiReaderSettings
+                {
+                    ReferenceResolution = ReferenceResolutionSetting.ResolveLocalReferences,
+                    RuleSet = ValidationRuleSet.GetDefaultRuleSet()
+                }
+                ).Read(stream, out var context);
+                if (context.Errors.Count != 0)
+                {
+                    var errorReport = new StringBuilder();
+
+                    foreach (var error in context.Errors)
+                    {
+                        errorReport.AppendLine(error.ToString());
+                    }
+
+                    throw new ArgumentException(String.Join(Environment.NewLine, context.Errors.Select(e => e.Message).ToArray()));
+                }
+            }
+
+            using (var outputStream = output?.Create())
+            {
+                TextWriter textWriter;
+
+                if (outputStream!=null)
+                {
+                    textWriter = new StreamWriter(outputStream);
+                } else
+                {
+                    textWriter = Console.Out;
+                }
+
+                var settings = new OpenApiWriterSettings()
+                {
+                    ReferenceInline = inline == true ? ReferenceInlineSetting.InlineLocalReferences : ReferenceInlineSetting.DoNotInlineReferences
+                };
+                IOpenApiWriter writer;
+                switch (format)
+                {
+                    case OpenApiFormat.Json:
+                        writer = new OpenApiJsonWriter(textWriter, settings);
+                        break;
+                    case OpenApiFormat.Yaml:
+                        writer = new OpenApiYamlWriter(textWriter, settings);
+                        break;
+                    default:
+                        throw new ArgumentException("Unknown format");
+                }
+
+                document.Serialize(writer,version );
+
+                textWriter.Flush();
+            }
+        }
+}
+}

src/Microsoft.OpenApi.Tool/Program.cs

@@ -0,0 +1,30 @@
+using System;
+using System.CommandLine;
+using System.CommandLine.Invocation;
+using System.IO;
+using System.Threading.Tasks;
+using Microsoft.OpenApi;
+
+namespace Microsoft.OpenApi.Tool
+{
+    class Program
+    {
+        static async Task<int> Main(string[] args)
+        {
+            var command = new RootCommand
+            {
+               new Option("--input") { Argument = new Argument<FileInfo>() },
+                new Option("--output") { Argument = new Argument<FileInfo>() },
+                new Option("--version") { Argument = new Argument<OpenApiSpecVersion>() },
+                new Option("--format") { Argument = new Argument<OpenApiFormat>() },
+                new Option("--inline") { Argument = new Argument<bool>() }
+            };
+
+            command.Handler = CommandHandler.Create<FileInfo,FileInfo,OpenApiSpecVersion,OpenApiFormat,bool>(
+                OpenApiService.ProcessOpenApiDocument);
+
+            // Parse the incoming args and invoke the handler
+            return await command.InvokeAsync(args);
+        }
+    }
+}

src/Microsoft.OpenApi/Any/OpenApiString.cs

@@ -14,6 +14,7 @@ public class OpenApiString : OpenApiPrimitive<string>
         /// Initializes the <see cref="OpenApiString"/> class.
         /// </summary>
         /// <param name="value"></param>
+        /// <param name="isExplicit">Used to indicate if a string is quoted.</param>
         public OpenApiString(string value, bool isExplicit = false)
             : base(value)
         {

src/Microsoft.OpenApi/Extensions/OpenApiSerializableExtensions.cs

@@ -50,6 +50,7 @@ public static void SerializeAsYaml<T>(this T element, Stream stream, OpenApiSpec
         /// <param name="stream">The given stream.</param>
         /// <param name="specVersion">The Open API specification version.</param>
         /// <param name="format">The output format (JSON or YAML).</param>
+        /// <param name="settings">Provide configuration settings for controlling writing output</param>
         public static void Serialize<T>(
             this T element,
             Stream stream,

src/Microsoft.OpenApi/Services/LoopDetector.cs

@@ -13,7 +13,6 @@ internal class LoopDetector
         /// <summary>
         /// Maintain history of traversals to avoid stack overflows from cycles
         /// </summary>
-        /// <param name="loopId">Any unique identifier for a stack.</param>
         /// <param name="key">Identifier used for current context.</param>
         /// <returns>If method returns false a loop was detected and the key is not added.</returns>
         public bool PushLoop<T>(T key)
@@ -39,7 +38,6 @@ public bool PushLoop<T>(T key)
         /// <summary>
         /// Exit from the context in cycle detection
         /// </summary>
-        /// <param name="loopid">Identifier of loop</param>
         public void PopLoop<T>()
         {
             if (_loopStacks[typeof(T)].Count > 0)
@@ -65,7 +63,6 @@ public void SaveLoop<T>(T loop)
         /// <summary>
         /// Reset loop tracking stack
         /// </summary>
-        /// <param name="loopid">Identifier of loop to clear</param>
         internal void ClearLoop<T>()
         {
             _loopStacks[typeof(T)].Clear();

src/Microsoft.OpenApi/Services/OpenApiDifferenceOperation.cs

@@ -3,6 +3,8 @@
 
 namespace Microsoft.OpenApi.Services
 {
+#pragma warning disable CS1591 // Missing XML comment for publicly visible type or member
+
     /// <summary>
     /// The open api difference operation.
     /// </summary>
@@ -12,4 +14,6 @@ public enum OpenApiDifferenceOperation
         Remove,
         Update
     }
+#pragma warning restore CS1591 // Missing XML comment for publicly visible type or member
+
 }

src/Microsoft.OpenApi/Writers/OpenApiJsonWriter.cs

@@ -14,6 +14,7 @@ public class OpenApiJsonWriter : OpenApiWriterBase
         /// Initializes a new instance of the <see cref="OpenApiJsonWriter"/> class.
         /// </summary>
         /// <param name="textWriter">The text writer.</param>
+        /// <param name="settings">Settings for controlling how the OpenAPI document will be written out.</param>
         public OpenApiJsonWriter(TextWriter textWriter, OpenApiWriterSettings settings = null) : base(textWriter, settings)
         {
         }

test/Microsoft.OpenApi.SmokeTests/ApiGurus.cs

@@ -71,7 +71,7 @@ JToken GetProp(JToken obj, string prop)
         }
 
         // Disable as some APIs are currently invalid [Theory(DisplayName = "APIs.guru")]
-        [MemberData(nameof(GetSchemas))]
+        // [MemberData(nameof(GetSchemas))]
         public async Task EnsureThatICouldParse(string url)
         {
             var response = await _httpClient.GetAsync(url);