Added support for inlining references when writing out API descriptions

darrelmiller · darrelmiller · commit f00c27cc0e10 · 2020-01-07T12:36:17.000-05:00
diff --git a/src/Microsoft.OpenApi.Readers/OpenApiReaderSettings.cs b/src/Microsoft.OpenApi.Readers/OpenApiReaderSettings.cs
@@ -1,4 +1,7 @@
-﻿using Microsoft.OpenApi.Any;
+﻿// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license. 
+
+using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Readers.ParseNodes;
 using Microsoft.OpenApi.Validations;
diff --git a/src/Microsoft.OpenApi.Workbench/MainModel.cs b/src/Microsoft.OpenApi.Workbench/MainModel.cs
@@ -4,13 +4,15 @@
 using System;
 using System.ComponentModel;
 using System.Diagnostics;
+using System.Globalization;
 using System.IO;
 using System.Text;
 using Microsoft.OpenApi.Extensions;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Readers;
 using Microsoft.OpenApi.Services;
 using Microsoft.OpenApi.Validations;
+using Microsoft.OpenApi.Writers;
 
 namespace Microsoft.OpenApi.Workbench
 {
@@ -31,6 +33,11 @@ public class MainModel : INotifyPropertyChanged
 
         private string _renderTime;
 
+        /// <summary>
+        /// Default format.
+        /// </summary>
+        private bool _Inline = false;
+
         /// <summary>
         /// Default format.
         /// </summary>
@@ -112,6 +119,16 @@ public OpenApiFormat Format
             }
         }
 
+        public bool Inline
+        {
+            get => _Inline;
+            set
+            {
+                _Inline = value;
+                OnPropertyChanged(nameof(Inline));
+            }
+        }
+
         public OpenApiSpecVersion Version
         {
             get => _version;
@@ -232,10 +249,14 @@ internal void ParseDocument()
         private string WriteContents(OpenApiDocument document)
         {
             var outputStream = new MemoryStream();
+            
             document.Serialize(
                 outputStream,
                 Version,
-                Format);
+                Format,
+                new OpenApiWriterSettings() {
+                    ReferenceInline = this.Inline == true ? ReferenceInlineSetting.InlineLocalReferences : ReferenceInlineSetting.DoNotInlineReferences
+                });
             
             outputStream.Position = 0;
 
diff --git a/src/Microsoft.OpenApi.Workbench/MainWindow.xaml b/src/Microsoft.OpenApi.Workbench/MainWindow.xaml
@@ -42,6 +42,7 @@
                         <RadioButton GroupName="Format" Content="V3.0.1" Padding="5" Height="24" VerticalAlignment="Top" IsChecked="{Binding IsV3_0}" />
                         <RadioButton GroupName="Format" Content="V2.0" Padding="5" Height="24" VerticalAlignment="Top" IsChecked="{Binding IsV2_0}" />
                     </StackPanel>
+                    <CheckBox Name="Inline" Content="Inline" IsChecked="{Binding Inline}" />
                 </StackPanel>
             </StackPanel>
             <TextBox x:Name="txtErrors"  Margin="10,10,10,10" TextWrapping="Wrap" Text="{Binding Errors}"  Background="{DynamicResource {x:Static SystemColors.ControlLightBrushKey}}" DockPanel.Dock="Top" MaxHeight="100" ScrollViewer.VerticalScrollBarVisibility="Auto" IsReadOnlyCaretVisible="True" IsManipulationEnabled="True" />
diff --git a/src/Microsoft.OpenApi/Extensions/OpenAPIWriterExtensions.cs b/src/Microsoft.OpenApi/Extensions/OpenAPIWriterExtensions.cs
@@ -0,0 +1,26 @@
+﻿using Microsoft.OpenApi.Writers;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace Microsoft.OpenApi
+{
+    internal static class OpenAPIWriterExtensions
+    {
+        /// <summary>
+        /// Temporary extension method until we add Settings property to IOpenApiWriter in next major version
+        /// </summary>
+        /// <param name="openApiWriter"></param>
+        /// <returns></returns>
+        internal static OpenApiWriterSettings GetSettings(this IOpenApiWriter openApiWriter) 
+        {
+            if (openApiWriter is OpenApiWriterBase)
+            {
+                return ((OpenApiWriterBase)openApiWriter).Settings;
+            }
+            return new OpenApiWriterSettings();
+        }
+    }
+}
diff --git a/src/Microsoft.OpenApi/Extensions/OpenApiSerializableExtensions.cs b/src/Microsoft.OpenApi/Extensions/OpenApiSerializableExtensions.cs
@@ -54,7 +54,8 @@ public static void Serialize<T>(
             this T element,
             Stream stream,
             OpenApiSpecVersion specVersion,
-            OpenApiFormat format)
+            OpenApiFormat format, 
+            OpenApiWriterSettings settings = null)
             where T : IOpenApiSerializable
         {
             if (stream == null)
@@ -67,10 +68,10 @@ public static void Serialize<T>(
             switch (format)
             {
                 case OpenApiFormat.Json:
-                    writer = new OpenApiJsonWriter(streamWriter);
+                    writer = new OpenApiJsonWriter(streamWriter,settings);
                     break;
                 case OpenApiFormat.Yaml:
-                    writer = new OpenApiYamlWriter(streamWriter);
+                    writer = new OpenApiYamlWriter(streamWriter, settings);
                     break;
                 default:
                     throw new OpenApiException(string.Format(SRResource.OpenApiFormatNotSupported, format));
@@ -86,6 +87,7 @@ public static void Serialize<T>(
         /// <param name="element">The Open API element.</param>
         /// <param name="writer">The output writer.</param>
         /// <param name="specVersion">Version of the specification the output should conform to</param>
+
         public static void Serialize<T>(this T element, IOpenApiWriter writer, OpenApiSpecVersion specVersion)
             where T : IOpenApiSerializable
         {
@@ -116,6 +118,7 @@ public static void Serialize<T>(this T element, IOpenApiWriter writer, OpenApiSp
             writer.Flush();
         }
 
+
         /// <summary>
         /// Serializes the <see cref="IOpenApiSerializable"/> to the Open API document as a string in JSON format.
         /// </summary>
diff --git a/src/Microsoft.OpenApi/Models/OpenApiCallback.cs b/src/Microsoft.OpenApi/Models/OpenApiCallback.cs
@@ -70,7 +70,7 @@ public void SerializeAsV3(IOpenApiWriter writer)
                 throw Error.ArgumentNull(nameof(writer));
             }
 
-            if (Reference != null)
+            if (Reference != null && writer.GetSettings().ReferenceInline != ReferenceInlineSetting.InlineLocalReferences)
             {
                 Reference.SerializeAsV3(writer);
                 return;
diff --git a/src/Microsoft.OpenApi/Models/OpenApiComponents.cs b/src/Microsoft.OpenApi/Models/OpenApiComponents.cs
@@ -76,6 +76,12 @@ public void SerializeAsV3(IOpenApiWriter writer)
                 throw Error.ArgumentNull(nameof(writer));
             }
 
+            // If references have been inlined we don't need the to render the components section
+            if (writer.GetSettings().ReferenceInline != ReferenceInlineSetting.DoNotInlineReferences)
+            {
+                return;  
+            }
+
             writer.WriteStartObject();
 
             // Serialize each referenceable object as full object without reference if the reference in the object points to itself.
diff --git a/src/Microsoft.OpenApi/Models/OpenApiExample.cs b/src/Microsoft.OpenApi/Models/OpenApiExample.cs
@@ -64,7 +64,7 @@ public void SerializeAsV3(IOpenApiWriter writer)
                 throw Error.ArgumentNull(nameof(writer));
             }
 
-            if (Reference != null)
+            if (Reference != null && writer.GetSettings().ReferenceInline != ReferenceInlineSetting.InlineLocalReferences)
             {
                 Reference.SerializeAsV3(writer);
                 return;
diff --git a/src/Microsoft.OpenApi/Models/OpenApiLink.cs b/src/Microsoft.OpenApi/Models/OpenApiLink.cs
@@ -71,7 +71,7 @@ public void SerializeAsV3(IOpenApiWriter writer)
                 throw Error.ArgumentNull(nameof(writer));
             }
 
-            if (Reference != null)
+            if (Reference != null && writer.GetSettings().ReferenceInline != ReferenceInlineSetting.InlineLocalReferences)
             {
                 Reference.SerializeAsV3(writer);
                 return;
diff --git a/src/Microsoft.OpenApi/Models/OpenApiParameter.cs b/src/Microsoft.OpenApi/Models/OpenApiParameter.cs
@@ -139,7 +139,7 @@ public void SerializeAsV3(IOpenApiWriter writer)
                 throw Error.ArgumentNull(nameof(writer));
             }
 
-            if (Reference != null)
+            if (Reference != null && writer.GetSettings().ReferenceInline != ReferenceInlineSetting.InlineLocalReferences)
             {
                 Reference.SerializeAsV3(writer);
                 return;
@@ -210,7 +210,7 @@ public void SerializeAsV2(IOpenApiWriter writer)
                 throw Error.ArgumentNull(nameof(writer));
             }
 
-            if (Reference != null)
+            if (Reference != null && writer.GetSettings().ReferenceInline != ReferenceInlineSetting.InlineLocalReferences)
             {
                 Reference.SerializeAsV2(writer);
                 return;
diff --git a/src/Microsoft.OpenApi/Models/OpenApiResponse.cs b/src/Microsoft.OpenApi/Models/OpenApiResponse.cs
@@ -61,7 +61,7 @@ public void SerializeAsV3(IOpenApiWriter writer)
                 throw Error.ArgumentNull(nameof(writer));
             }
 
-            if (Reference != null)
+            if (Reference != null && writer.GetSettings().ReferenceInline != ReferenceInlineSetting.InlineLocalReferences)
             {
                 Reference.SerializeAsV3(writer);
                 return;
@@ -105,7 +105,7 @@ public void SerializeAsV2(IOpenApiWriter writer)
                 throw Error.ArgumentNull(nameof(writer));
             }
 
-            if (Reference != null)
+            if (Reference != null && writer.GetSettings().ReferenceInline != ReferenceInlineSetting.InlineLocalReferences)
             {
                 Reference.SerializeAsV2(writer);
                 return;
diff --git a/src/Microsoft.OpenApi/Models/OpenApiSchema.cs b/src/Microsoft.OpenApi/Models/OpenApiSchema.cs
@@ -251,7 +251,7 @@ public void SerializeAsV3(IOpenApiWriter writer)
                 throw Error.ArgumentNull(nameof(writer));
             }
 
-            if (Reference != null)
+            if (Reference != null && writer.GetSettings().ReferenceInline != ReferenceInlineSetting.InlineLocalReferences)
             {
                 Reference.SerializeAsV3(writer);
                 return;
@@ -424,7 +424,8 @@ internal void SerializeAsV2(
                 throw Error.ArgumentNull(nameof(writer));
             }
 
-            if (Reference != null)
+            
+            if (Reference != null && writer.GetSettings().ReferenceInline != ReferenceInlineSetting.InlineLocalReferences)
             {
                 Reference.SerializeAsV2(writer);
                 return;
diff --git a/src/Microsoft.OpenApi/Writers/OpenApiJsonWriter.cs b/src/Microsoft.OpenApi/Writers/OpenApiJsonWriter.cs
@@ -14,7 +14,7 @@ public class OpenApiJsonWriter : OpenApiWriterBase
         /// Initializes a new instance of the <see cref="OpenApiJsonWriter"/> class.
         /// </summary>
         /// <param name="textWriter">The text writer.</param>
-        public OpenApiJsonWriter(TextWriter textWriter) : base(textWriter)
+        public OpenApiJsonWriter(TextWriter textWriter, OpenApiWriterSettings settings = null) : base(textWriter, settings)
         {
         }
 
diff --git a/src/Microsoft.OpenApi/Writers/OpenApiWriterBase.cs b/src/Microsoft.OpenApi/Writers/OpenApiWriterBase.cs
@@ -14,6 +14,11 @@ namespace Microsoft.OpenApi.Writers
     /// </summary>
     public abstract class OpenApiWriterBase : IOpenApiWriter
     {
+        /// <summary>
+        /// Settings for controlling how the OpenAPI document will be written out.
+        /// </summary>
+        public OpenApiWriterSettings Settings { get; set; }
+
         /// <summary>
         /// The indentation string to prepand to each line for each indentation level.
         /// </summary>
@@ -41,6 +46,20 @@ public OpenApiWriterBase(TextWriter textWriter)
             Scopes = new Stack<Scope>();
         }
 
+        /// <summary>
+        /// 
+        /// </summary>
+        /// <param name="textWriter"></param>
+        /// <param name="settings"></param>
+        public OpenApiWriterBase(TextWriter textWriter, OpenApiWriterSettings settings = null) : this(textWriter)
+        {
+            if (settings == null)
+            {
+                settings = new OpenApiWriterSettings();
+            }
+            Settings = settings;
+        }
+
         /// <summary>
         /// Base Indentation Level.
         /// This denotes how many indentations are needed for the property in the base object.
diff --git a/src/Microsoft.OpenApi/Writers/OpenApiWriterSettings.cs b/src/Microsoft.OpenApi/Writers/OpenApiWriterSettings.cs
@@ -0,0 +1,33 @@
+﻿
+namespace Microsoft.OpenApi.Writers
+{
+    /// <summary>
+    /// Indicates if and when the reader should convert references into complete object renderings
+    /// </summary>
+    public enum ReferenceInlineSetting
+    {
+        /// <summary>
+        /// Create placeholder objects with an OpenApiReference instance and UnresolvedReference set to true.
+        /// </summary>
+        DoNotInlineReferences,
+        /// <summary>
+        /// Convert local references to references of valid domain objects.
+        /// </summary>
+        InlineLocalReferences,
+        /// <summary>
+        /// Convert all references to references of valid domain objects.
+        /// </summary>
+        InlineAllReferences
+    }
+
+    /// <summary>
+    /// Configuration settings to control how OpenAPI documents are written
+    /// </summary>
+    public class OpenApiWriterSettings
+    {
+        /// <summary>
+        /// Indicates how references in the source document should be handled.
+        /// </summary>
+        public ReferenceInlineSetting ReferenceInline { get; set; } = ReferenceInlineSetting.DoNotInlineReferences;
+    }
+}
diff --git a/src/Microsoft.OpenApi/Writers/OpenApiYamlWriter.cs b/src/Microsoft.OpenApi/Writers/OpenApiYamlWriter.cs
@@ -14,11 +14,12 @@ public class OpenApiYamlWriter : OpenApiWriterBase
         /// Initializes a new instance of the <see cref="OpenApiYamlWriter"/> class.
         /// </summary>
         /// <param name="textWriter">The text writer.</param>
-        public OpenApiYamlWriter(TextWriter textWriter) : base(textWriter)
+        /// <param name="settings"></param>
+        public OpenApiYamlWriter(TextWriter textWriter, OpenApiWriterSettings settings = null) : base(textWriter, settings)
         {
+           
         }
 
-
         /// <summary>
         /// Base Indentation Level.
         /// This denotes how many indentations are needed for the property in the base object.

Original file line number	Diff line number	Diff line change
`@@ -70,7 +70,7 @@ public void SerializeAsV3(IOpenApiWriter writer)`
`70`	`70`	`throw Error.ArgumentNull(nameof(writer));`
`71`	`71`	`}`
`72`	`72`
`73`		`- if (Reference != null)`
	`73`	`+ if (Reference != null && writer.GetSettings().ReferenceInline != ReferenceInlineSetting.InlineLocalReferences)`
`74`	`74`	`{`
`75`	`75`	`Reference.SerializeAsV3(writer);`
`76`	`76`	`return;`
Original file line number	Diff line number	Diff line change
`@@ -64,7 +64,7 @@ public void SerializeAsV3(IOpenApiWriter writer)`
`64`	`64`	`throw Error.ArgumentNull(nameof(writer));`
`65`	`65`	`}`
`66`	`66`
`67`		`- if (Reference != null)`
	`67`	`+ if (Reference != null && writer.GetSettings().ReferenceInline != ReferenceInlineSetting.InlineLocalReferences)`
`68`	`68`	`{`
`69`	`69`	`Reference.SerializeAsV3(writer);`
`70`	`70`	`return;`
Original file line number	Diff line number	Diff line change
`@@ -71,7 +71,7 @@ public void SerializeAsV3(IOpenApiWriter writer)`
`71`	`71`	`throw Error.ArgumentNull(nameof(writer));`
`72`	`72`	`}`
`73`	`73`
`74`		`- if (Reference != null)`
	`74`	`+ if (Reference != null && writer.GetSettings().ReferenceInline != ReferenceInlineSetting.InlineLocalReferences)`
`75`	`75`	`{`
`76`	`76`	`Reference.SerializeAsV3(writer);`
`77`	`77`	`return;`
Original file line number	Diff line number	Diff line change
`@@ -139,7 +139,7 @@ public void SerializeAsV3(IOpenApiWriter writer)`
`139`	`139`	`throw Error.ArgumentNull(nameof(writer));`
`140`	`140`	`}`
`141`	`141`
`142`		`- if (Reference != null)`
	`142`	`+ if (Reference != null && writer.GetSettings().ReferenceInline != ReferenceInlineSetting.InlineLocalReferences)`
`143`	`143`	`{`
`144`	`144`	`Reference.SerializeAsV3(writer);`
`145`	`145`	`return;`
`@@ -210,7 +210,7 @@ public void SerializeAsV2(IOpenApiWriter writer)`
`210`	`210`	`throw Error.ArgumentNull(nameof(writer));`
`211`	`211`	`}`
`212`	`212`
`213`		`- if (Reference != null)`
	`213`	`+ if (Reference != null && writer.GetSettings().ReferenceInline != ReferenceInlineSetting.InlineLocalReferences)`
`214`	`214`	`{`
`215`	`215`	`Reference.SerializeAsV2(writer);`
`216`	`216`	`return;`