Add summary and description to OpenApiReference object

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

@@ -19,8 +19,10 @@ internal interface IOpenApiVersionService
         /// </summary>
         /// <param name="reference">The reference string.</param>
         /// <param name="type">The type of the reference.</param>
+        /// <param name="summary">The summary of the reference.</param>
+        /// <param name="description">A reference description</param>
         /// <returns>The <see cref="OpenApiReference"/> object or null.</returns>
-        OpenApiReference ConvertToOpenApiReference(string reference, ReferenceType? type);
+        OpenApiReference ConvertToOpenApiReference(string reference, ReferenceType? type, string summary = null, string description = null);
 
         /// <summary>
         /// Loads an OpenAPI Element from a document fragment
@@ -36,5 +38,13 @@ internal interface IOpenApiVersionService
         /// <param name="rootNode">RootNode containing the information to be converted into an OpenAPI Document</param>
         /// <returns>Instance of OpenApiDocument populated with data from rootNode</returns>
         OpenApiDocument LoadDocument(RootNode rootNode);
+
+        /// <summary>
+        /// Gets the description and summary scalar values in a reference object for V3.1 support
+        /// </summary>
+        /// <param name="mapNode">A YamlMappingNode.</param>
+        /// <param name="scalarValue">The scalar value we're parsing.</param>
+        /// <returns>The resulting node value.</returns>
+        string GetReferenceScalarValues(MapNode mapNode, string scalarValue);
     }
 }

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

@@ -1,6 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
         <TargetFrameworks>netstandard2.0</TargetFrameworks>
+        <LangVersion>9.0</LangVersion>
         <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
         <PackageIconUrl>http://go.microsoft.com/fwlink/?LinkID=288890</PackageIconUrl>
         <PackageProjectUrl>https://github.com/Microsoft/OpenAPI.NET</PackageProjectUrl>

src/Microsoft.OpenApi.Readers/ParseNodes/MapNode.cs

@@ -181,13 +181,13 @@ public override string GetRaw()
             return x.Serialize(_node);
         }
 
-        public T GetReferencedObject<T>(ReferenceType referenceType, string referenceId)
+        public T GetReferencedObject<T>(ReferenceType referenceType, string referenceId, string summary = null, string description = null)
             where T : IOpenApiReferenceable, new()
         {
             return new T()
             {
                 UnresolvedReference = true,
-                Reference = Context.VersionService.ConvertToOpenApiReference(referenceId, referenceType)
+                Reference = Context.VersionService.ConvertToOpenApiReference(referenceId, referenceType, summary, description)
             };
         }
 

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

@@ -134,7 +134,7 @@ private static ReferenceType GetReferenceTypeV2FromName(string referenceType)
         /// <summary>
         /// Parse the string to a <see cref="OpenApiReference"/> object.
         /// </summary>
-        public OpenApiReference ConvertToOpenApiReference(string reference, ReferenceType? type)
+        public OpenApiReference ConvertToOpenApiReference(string reference, ReferenceType? type, string summary = null, string description = null)
         {
             if (!string.IsNullOrWhiteSpace(reference))
             {
@@ -221,5 +221,11 @@ public T LoadElement<T>(ParseNode node) where T : IOpenApiElement
         {
             return (T)_loaders[typeof(T)](node);
         }
+
+        /// <inheritdoc />
+        public string GetReferenceScalarValues(MapNode mapNode, string scalarValue)
+        {
+            throw new InvalidOperationException();
+        }
     }
 }

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

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license. 
 
+using System.Linq;
 using Microsoft.OpenApi.Extensions;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Readers.ParseNodes;
@@ -55,7 +56,10 @@ public static OpenApiExample LoadExample(ParseNode node)
             var pointer = mapNode.GetReferencePointer();
             if (pointer != null)
             {
-                return mapNode.GetReferencedObject<OpenApiExample>(ReferenceType.Example, pointer);
+                var description = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Description);
+                var summary = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Summary);                
+
+                return mapNode.GetReferencedObject<OpenApiExample>(ReferenceType.Example, pointer, summary, description);
             }
 
             var example = new OpenApiExample();

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

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license. 
 
+using System.Linq;
 using Microsoft.OpenApi.Extensions;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Readers.ParseNodes;
@@ -89,7 +90,10 @@ public static OpenApiHeader LoadHeader(ParseNode node)
             var pointer = mapNode.GetReferencePointer();
             if (pointer != null)
             {
-                return mapNode.GetReferencedObject<OpenApiHeader>(ReferenceType.Header, pointer);
+                var description = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Description);
+                var summary = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Summary);
+
+                return mapNode.GetReferencedObject<OpenApiHeader>(ReferenceType.Header, pointer, summary, description);
             }
 
             var header = new OpenApiHeader();

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

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license. 
 
+using System.Linq;
 using Microsoft.OpenApi.Extensions;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Readers.ParseNodes;
@@ -61,7 +62,10 @@ public static OpenApiLink LoadLink(ParseNode node)
             var pointer = mapNode.GetReferencePointer();
             if (pointer != null)
             {
-                return mapNode.GetReferencedObject<OpenApiLink>(ReferenceType.Link, pointer);
+                var description = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Description);
+                var summary = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Summary);
+
+                return mapNode.GetReferencedObject<OpenApiLink>(ReferenceType.Link, pointer, summary, description);
             }
 
             ParseMap(mapNode, link, _linkFixedFields, _linkPatternFields);

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

@@ -146,7 +146,10 @@ public static OpenApiParameter LoadParameter(ParseNode node)
             var pointer = mapNode.GetReferencePointer();
             if (pointer != null)
             {
-                return mapNode.GetReferencedObject<OpenApiParameter>(ReferenceType.Parameter, pointer);
+                var description = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Description);
+                var summary = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Summary);
+
+                return mapNode.GetReferencedObject<OpenApiParameter>(ReferenceType.Parameter, pointer, summary, description);
             }
 
             var parameter = new OpenApiParameter();

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

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license. 
 
+using System.Linq;
 using Microsoft.OpenApi.Extensions;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Readers.ParseNodes;
@@ -60,10 +61,13 @@ public static OpenApiPathItem LoadPathItem(ParseNode node)
 
             if (pointer != null)
             {
+                var description = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Description);
+                var summary = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Summary);
+
                 return new OpenApiPathItem()
                 {
                     UnresolvedReference = true,
-                    Reference = node.Context.VersionService.ConvertToOpenApiReference(pointer, ReferenceType.PathItem)
+                    Reference = node.Context.VersionService.ConvertToOpenApiReference(pointer, ReferenceType.PathItem, summary, description)
                 };
             }
 

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

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license. 
 
+using System.Linq;
 using Microsoft.OpenApi.Extensions;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Readers.ParseNodes;
@@ -49,7 +50,10 @@ public static OpenApiRequestBody LoadRequestBody(ParseNode node)
             var pointer = mapNode.GetReferencePointer();
             if (pointer != null)
             {
-                return mapNode.GetReferencedObject<OpenApiRequestBody>(ReferenceType.RequestBody, pointer);
+                var description = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Description);
+                var summary = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Summary);
+
+                return mapNode.GetReferencedObject<OpenApiRequestBody>(ReferenceType.RequestBody, pointer, summary, description);
             }
 
             var requestBody = new OpenApiRequestBody();

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

@@ -2,6 +2,7 @@
 // Licensed under the MIT license. 
 
 using System.Collections.Generic;
+using System.Linq;
 using Microsoft.OpenApi.Extensions;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Readers.ParseNodes;
@@ -55,7 +56,11 @@ public static OpenApiResponse LoadResponse(ParseNode node)
             var pointer = mapNode.GetReferencePointer();
             if (pointer != null)
             {
-                return mapNode.GetReferencedObject<OpenApiResponse>(ReferenceType.Response, pointer);
+
+                var description = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Description);
+                var summary = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Summary);
+
+                return mapNode.GetReferencedObject<OpenApiResponse>(ReferenceType.Response, pointer, summary, description);
             }
 
             var response = new OpenApiResponse();

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

@@ -7,6 +7,7 @@
 using Microsoft.OpenApi.Readers.ParseNodes;
 using System.Collections.Generic;
 using System.Globalization;
+using System.Linq;
 
 namespace Microsoft.OpenApi.Readers.V3
 {
@@ -277,16 +278,18 @@ public static OpenApiSchema LoadSchema(ParseNode node)
             var mapNode = node.CheckMapNode(OpenApiConstants.Schema);
 
             var pointer = mapNode.GetReferencePointer();
-
             if (pointer != null)
-            {
-                return new OpenApiSchema()
+            {                   
+                var description = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Description);
+                var summary = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Summary);
+
+                return new OpenApiSchema
                 {
                     UnresolvedReference = true,
-                    Reference = node.Context.VersionService.ConvertToOpenApiReference(pointer, ReferenceType.Schema)
+                    Reference = node.Context.VersionService.ConvertToOpenApiReference(pointer, ReferenceType.Schema, summary, description)
                 };
             }
-
+            
             var schema = new OpenApiSchema();
 
             foreach (var propertyNode in mapNode)

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

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license. 
 
+using System.Linq;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Readers.ParseNodes;
 
@@ -15,14 +16,20 @@ internal static partial class OpenApiV3Deserializer
         public static OpenApiSecurityRequirement LoadSecurityRequirement(ParseNode node)
         {
             var mapNode = node.CheckMapNode("security");
-
+            string description = null;
+            string summary = null;
+
             var securityRequirement = new OpenApiSecurityRequirement();
 
             foreach (var property in mapNode)
             {
-                var scheme = LoadSecuritySchemeByReference(
-                    mapNode.Context,
-                    property.Name);
+                if(property.Name.Equals("description") || property.Name.Equals("summary"))
+                {
+                    description = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Description);
+                    summary = node.Context.VersionService.GetReferenceScalarValues(mapNode, OpenApiConstants.Summary);
+                }
+
+                var scheme = LoadSecuritySchemeByReference(mapNode.Context, property.Name, summary, description);
 
                 var scopes = property.Value.CreateSimpleList(value => value.GetScalarValue());
 
@@ -42,13 +49,17 @@ public static OpenApiSecurityRequirement LoadSecurityRequirement(ParseNode node)
 
         private static OpenApiSecurityScheme LoadSecuritySchemeByReference(
             ParsingContext context,
-            string schemeName)
+            string schemeName,
+            string summary = null,
+            string description = null)
         {
             var securitySchemeObject = new OpenApiSecurityScheme()
             {
                 UnresolvedReference = true,
                 Reference = new OpenApiReference()
                 {
+                    Summary = summary,
+                    Description = description,
                     Id = schemeName,
                     Type = ReferenceType.SecurityScheme
                 }

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

@@ -3,6 +3,7 @@
 
 using System;
 using System.Collections.Generic;
+using System.Linq;
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Exceptions;
 using Microsoft.OpenApi.Extensions;
@@ -67,9 +68,13 @@ public OpenApiV3VersionService(OpenApiDiagnostic diagnostic)
         /// </summary>
         /// <param name="reference">The URL of the reference</param>
         /// <param name="type">The type of object refefenced based on the context of the reference</param>
+        /// <param name="summary">The summary of the reference</param>
+        /// <param name="description">A reference description</param>
         public OpenApiReference ConvertToOpenApiReference(
             string reference,
-            ReferenceType? type)
+            ReferenceType? type,
+            string summary = null,
+            string description = null)
         {
             if (!string.IsNullOrWhiteSpace(reference))
             {
@@ -80,6 +85,8 @@ public OpenApiReference ConvertToOpenApiReference(
                     {
                         return new OpenApiReference
                         {
+                            Summary = summary,
+                            Description = description,
                             Type = type,
                             Id = reference
                         };
@@ -89,6 +96,8 @@ public OpenApiReference ConvertToOpenApiReference(
                     // or a simple string-style reference for tag and security scheme.
                     return new OpenApiReference
                     {
+                        Summary = summary,
+                        Description = description,
                         Type = type,
                         ExternalResource = segments[0]
                     };
@@ -100,7 +109,7 @@ public OpenApiReference ConvertToOpenApiReference(
                         // "$ref": "#/components/schemas/Pet"
                         try
                         {
-                            return ParseLocalReference(segments[1]);
+                            return ParseLocalReference(segments[1], summary, description);
                         }
                         catch (OpenApiException ex)
                         {
@@ -131,6 +140,8 @@ public OpenApiReference ConvertToOpenApiReference(
 
                     return new OpenApiReference
                     {
+                        Summary = summary,
+                        Description = description,
                         ExternalResource = segments[0],
                         Type = type,
                         Id = id
@@ -151,7 +162,22 @@ public T LoadElement<T>(ParseNode node) where T : IOpenApiElement
             return (T)_loaders[typeof(T)](node);
         }
 
-        private OpenApiReference ParseLocalReference(string localReference)
+
+        /// <inheritdoc />
+        public string GetReferenceScalarValues(MapNode mapNode, string scalarValue)
+        {
+            if (mapNode.Any(static x => !"$ref".Equals(x.Name, StringComparison.OrdinalIgnoreCase)))
+            {
+                var valueNode = mapNode.Where(x => x.Name.Equals(scalarValue))
+                .Select(static x => x.Value).OfType<ValueNode>().FirstOrDefault();
+
+                return valueNode.GetScalarValue();
+            }
+
+            return null;
+        }
+
+        private OpenApiReference ParseLocalReference(string localReference, string summary = null, string description = null)
         {
             if (string.IsNullOrWhiteSpace(localReference))
             {
@@ -170,7 +196,16 @@ private OpenApiReference ParseLocalReference(string localReference)
                     {
                         refId = "/" + segments[3];
                     };
-                    return new OpenApiReference { Type = referenceType, Id = refId };
+
+                    var parsedReference = new OpenApiReference
+                    {
+                        Summary = summary,
+                        Description = description,
+                        Type = referenceType,
+                        Id = refId
+                    };
+
+                    return parsedReference;
                 }
             }