Merge pull request #559 from microsoft/issue/288

Add support for $ref in PathItems

Author: darrelmiller

src/Microsoft.OpenApi.Readers/V2/OpenApiPathItemDeserializer.cs

@@ -18,7 +18,8 @@ internal static partial class OpenApiV2Deserializer
             {
                 "$ref", (o, n) =>
                 {
-                    /* Not supported yet */
+                    o.Reference = new OpenApiReference() { ExternalResource = n.GetScalarValue() };
+                    o.UnresolvedReference =true;
                 }
             },
             {"get", (o, n) => o.AddOperation(OperationType.Get, LoadOperation(n))},

src/Microsoft.OpenApi.Readers/V3/OpenApiPathItemDeserializer.cs

@@ -15,7 +15,13 @@ internal static partial class OpenApiV3Deserializer
     {
         private static readonly FixedFieldMap<OpenApiPathItem> _pathItemFixedFields = new FixedFieldMap<OpenApiPathItem>
         {
-            // $ref
+            
+            {
+                "$ref", (o,n) => {
+                    o.Reference = new OpenApiReference() { ExternalResource = n.GetScalarValue() };
+                    o.UnresolvedReference =true;
+                }  
+            },
             {
                 "summary", (o, n) =>
                 {

src/Microsoft.OpenApi/Models/OpenApiPathItem.cs

@@ -2,7 +2,6 @@
 // Licensed under the MIT license. 
 
 using System.Collections.Generic;
-using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Extensions;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Writers;
@@ -12,7 +11,7 @@ namespace Microsoft.OpenApi.Models
     /// <summary>
     /// Path Item Object: to describe the operations available on a single path.
     /// </summary>
-    public class OpenApiPathItem : IOpenApiSerializable, IOpenApiExtensible
+    public class OpenApiPathItem : IOpenApiSerializable, IOpenApiExtensible, IOpenApiReferenceable
     {
         /// <summary>
         /// An optional, string summary, intended to apply to all operations in this path.
@@ -46,6 +45,16 @@ public class OpenApiPathItem : IOpenApiSerializable, IOpenApiExtensible
         /// </summary>
         public IDictionary<string, IOpenApiExtension> Extensions { get; set; } = new Dictionary<string, IOpenApiExtension>();
 
+        /// <summary>
+        /// Indicates if object is populated with data or is just a reference to the data
+        /// </summary>
+        public bool UnresolvedReference { get; set; }
+
+        /// <summary>
+        /// Reference object.
+        /// </summary>
+        public OpenApiReference Reference { get; set; }
+
         /// <summary>
         /// Add one operation into this path item.
         /// </summary>
@@ -66,33 +75,14 @@ public void SerializeAsV3(IOpenApiWriter writer)
                 throw Error.ArgumentNull(nameof(writer));
             }
 
-            writer.WriteStartObject();
-
-            // summary
-            writer.WriteProperty(OpenApiConstants.Summary, Summary);
-
-            // description
-            writer.WriteProperty(OpenApiConstants.Description, Description);
-
-            // operations
-            foreach (var operation in Operations)
+            if (Reference != null && writer.GetSettings().ReferenceInline != ReferenceInlineSetting.InlineAllReferences)
             {
-                writer.WriteOptionalObject(
-                    operation.Key.GetDisplayName(),
-                    operation.Value,
-                    (w, o) => o.SerializeAsV3(w));
+                Reference.SerializeAsV3(writer);
+                return;
             }
 
-            // servers
-            writer.WriteOptionalCollection(OpenApiConstants.Servers, Servers, (w, s) => s.SerializeAsV3(w));
-
-            // parameters
-            writer.WriteOptionalCollection(OpenApiConstants.Parameters, Parameters, (w, p) => p.SerializeAsV3(w));
-
-            // specification extensions
-            writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi3_0);
+            SerializeAsV3WithoutReference(writer);
 
-            writer.WriteEndObject();
         }
 
         /// <summary>
@@ -105,6 +95,21 @@ public void SerializeAsV2(IOpenApiWriter writer)
                 throw Error.ArgumentNull(nameof(writer));
             }
 
+            if (Reference != null && writer.GetSettings().ReferenceInline != ReferenceInlineSetting.InlineAllReferences)
+            {
+                Reference.SerializeAsV2(writer);
+                return;
+            }
+
+            SerializeAsV2WithoutReference(writer);
+        }
+
+        /// <summary>
+        /// Serialize inline PathItem in OpenAPI V2
+        /// </summary>
+        /// <param name="writer"></param>
+        public void SerializeAsV2WithoutReference(IOpenApiWriter writer)
+        {
             writer.WriteStartObject();
 
             // operations except "trace"
@@ -133,6 +138,43 @@ public void SerializeAsV2(IOpenApiWriter writer)
             // specification extensions
             writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi2_0);
 
+            writer.WriteEndObject();
+
+        }
+
+        /// <summary>
+        /// Serialize inline PathItem in OpenAPI V3
+        /// </summary>
+        /// <param name="writer"></param>
+        public void SerializeAsV3WithoutReference(IOpenApiWriter writer)
+        {
+
+            writer.WriteStartObject();
+
+            // summary
+            writer.WriteProperty(OpenApiConstants.Summary, Summary);
+
+            // description
+            writer.WriteProperty(OpenApiConstants.Description, Description);
+
+            // operations
+            foreach (var operation in Operations)
+            {
+                writer.WriteOptionalObject(
+                    operation.Key.GetDisplayName(),
+                    operation.Value,
+                    (w, o) => o.SerializeAsV3(w));
+            }
+
+            // servers
+            writer.WriteOptionalCollection(OpenApiConstants.Servers, Servers, (w, s) => s.SerializeAsV3(w));
+
+            // parameters
+            writer.WriteOptionalCollection(OpenApiConstants.Parameters, Parameters, (w, p) => p.SerializeAsV3(w));
+
+            // specification extensions
+            writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi3_0);
+
             writer.WriteEndObject();
         }
     }

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

@@ -1,6 +1,6 @@
 <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
-        <TargetFrameworks>net462</TargetFrameworks>
+        <TargetFrameworks>net462;net50</TargetFrameworks>
         <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
         <Authors></Authors>
         <Company>Microsoft</Company>

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

@@ -1,6 +1,6 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
-    <TargetFrameworks>net462</TargetFrameworks>
+    <TargetFrameworks>net462;net50</TargetFrameworks>
     <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
     <Authors></Authors>
     <Company>Microsoft</Company>

test/Microsoft.OpenApi.Tests/PublicApi/PublicApi.approved.txt

@@ -695,18 +695,22 @@ namespace Microsoft.OpenApi.Models
         public void SerializeAsV3(Microsoft.OpenApi.Writers.IOpenApiWriter writer) { }
         public void SerializeAsV3WithoutReference(Microsoft.OpenApi.Writers.IOpenApiWriter writer) { }
     }
-    public class OpenApiPathItem : Microsoft.OpenApi.Interfaces.IOpenApiElement, Microsoft.OpenApi.Interfaces.IOpenApiExtensible, Microsoft.OpenApi.Interfaces.IOpenApiSerializable
+    public class OpenApiPathItem : Microsoft.OpenApi.Interfaces.IOpenApiElement, Microsoft.OpenApi.Interfaces.IOpenApiExtensible, Microsoft.OpenApi.Interfaces.IOpenApiReferenceable, Microsoft.OpenApi.Interfaces.IOpenApiSerializable
     {
         public OpenApiPathItem() { }
         public string Description { get; set; }
         public System.Collections.Generic.IDictionary<string, Microsoft.OpenApi.Interfaces.IOpenApiExtension> Extensions { get; set; }
         public System.Collections.Generic.IDictionary<Microsoft.OpenApi.Models.OperationType, Microsoft.OpenApi.Models.OpenApiOperation> Operations { get; set; }
         public System.Collections.Generic.IList<Microsoft.OpenApi.Models.OpenApiParameter> Parameters { get; set; }
+        public Microsoft.OpenApi.Models.OpenApiReference Reference { get; set; }
         public System.Collections.Generic.IList<Microsoft.OpenApi.Models.OpenApiServer> Servers { get; set; }
         public string Summary { get; set; }
+        public bool UnresolvedReference { get; set; }
         public void AddOperation(Microsoft.OpenApi.Models.OperationType operationType, Microsoft.OpenApi.Models.OpenApiOperation operation) { }
         public void SerializeAsV2(Microsoft.OpenApi.Writers.IOpenApiWriter writer) { }
+        public void SerializeAsV2WithoutReference(Microsoft.OpenApi.Writers.IOpenApiWriter writer) { }
         public void SerializeAsV3(Microsoft.OpenApi.Writers.IOpenApiWriter writer) { }
+        public void SerializeAsV3WithoutReference(Microsoft.OpenApi.Writers.IOpenApiWriter writer) { }
     }
     public class OpenApiPaths : Microsoft.OpenApi.Models.OpenApiExtensibleDictionary<Microsoft.OpenApi.Models.OpenApiPathItem>
     {