Add the documentation links from Links annotations in CSDL to OpenAPI Operations

src/Microsoft.OpenApi.OData.Reader/Edm/EdmAnnotationExtensions.cs

@@ -9,9 +9,11 @@
 using System.Linq;
 using Microsoft.OData.Edm;
 using Microsoft.OData.Edm.Vocabularies;
+using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.OData.Common;
 using Microsoft.OpenApi.OData.Vocabulary;
 using Microsoft.OpenApi.OData.Vocabulary.Authorization;
+using Microsoft.OpenApi.OData.Vocabulary.Core;
 
 namespace Microsoft.OpenApi.OData.Edm
 {
@@ -256,6 +258,21 @@ public static IEnumerable<T> GetCollection<T>(this IEdmModel model, IEdmVocabula
             });
         }
 
+        /// <summary>
+        /// Gets the links record value (a complex type) for the given <see cref="IEdmVocabularyAnnotatable"/>.
+        /// </summary>
+        /// <param name="model">The Edm model.</param>
+        /// <param name="target">The Edm target.</param>
+        /// <param name="linkRel">The link relation type for path operation.</param>
+        /// <returns>Null or the links record value (a complex type) for this annotation.</returns>
+        public static Link GetLinkRecord(this IEdmModel model, IEdmVocabularyAnnotatable target, string linkRel)
+        {
+            Utils.CheckArgumentNull(model, nameof(model));
+            Utils.CheckArgumentNull(target, nameof(target));
+
+            return model.GetCollection<Link>(target, CoreConstants.Links)?.FirstOrDefault(x => x.Rel == linkRel);
+        }
+
         /// <summary>
         /// Create the corresponding Authorization object.
         /// </summary>

src/Microsoft.OpenApi.OData.Reader/Edm/ODataContext.cs

@@ -177,7 +177,7 @@ internal IEnumerable<DeprecatedRevisionsType> GetDeprecationInformations(IEdmVoc
         {
             return annotable == null ?
                 Enumerable.Empty<DeprecatedRevisionsType>() :
-                    (Model?.GetCollection<DeprecatedRevisionsType>(annotable, "Org.OData.Core.V1.Revisions") ?? 
+                    (Model?.GetCollection<DeprecatedRevisionsType>(annotable, CoreConstants.Revisions) ?? 
                     Enumerable.Empty<DeprecatedRevisionsType>());
         }
     }

src/Microsoft.OpenApi.OData.Reader/OpenApiConvertSettings.cs

@@ -8,6 +8,7 @@
 using Microsoft.OpenApi.OData.Common;
 using Microsoft.OpenApi.OData.Edm;
 using Microsoft.OpenApi.OData.Extensions;
+using Microsoft.OpenApi.OData.Vocabulary.Core;
 
 namespace Microsoft.OpenApi.OData
 {
@@ -179,6 +180,11 @@ public string PathPrefix
         /// </summary>
         public bool ShowMsDosGroupPath { get; set; } = true;
 
+        /// <summary>
+        /// Gets/sets links to external documentation for operations
+        /// </summary>
+        public bool ShowExternalDocs { get; set; } = true;
+
         /// <summary>
         /// Gets/sets a the path provider.
         /// </summary>
@@ -259,6 +265,20 @@ public string PathPrefix
         /// </summary>
         public bool UseSuccessStatusCodeRange { get; set; } = false;
 
+        /// <summary>
+        /// Get/Sets a dictionary containing a mapping of HTTP methods to custom link relation types 
+        /// </summary>
+        public Dictionary<LinkRelKey, string> CustomHttpMethodLinkRelMapping { get; set; } = new()
+        {
+            { LinkRelKey.List, "https://graph.microsoft.com/rels/docs/list" },
+            { LinkRelKey.ReadByKey, "https://graph.microsoft.com/rels/docs/get" },
+            { LinkRelKey.Create, "https://graph.microsoft.com/rels/docs/create" },
+            { LinkRelKey.Update, "https://graph.microsoft.com/rels/docs/update" },
+            { LinkRelKey.Delete, "https://graph.microsoft.com/rels/docs/delete" },
+            { LinkRelKey.Action, "https://graph.microsoft.com/rels/docs/action" },
+            { LinkRelKey.Function, "https://graph.microsoft.com/rels/docs/function" }
+        };
+
         internal OpenApiConvertSettings Clone()
         {
             var newSettings = new OpenApiConvertSettings
@@ -288,6 +308,7 @@ internal OpenApiConvertSettings Clone()
                 RequireDerivedTypesConstraintForBoundOperations = this.RequireDerivedTypesConstraintForBoundOperations,
                 ShowSchemaExamples = this.ShowSchemaExamples,
                 ShowRootPath = this.ShowRootPath,
+                ShowExternalDocs = this.ShowExternalDocs,
                 PathProvider = this.PathProvider,
                 EnableDollarCountPath = this.EnableDollarCountPath,
                 AddSingleQuotesForStringParameters = this.AddSingleQuotesForStringParameters,
@@ -300,6 +321,7 @@ internal OpenApiConvertSettings Clone()
                 RequireRestrictionAnnotationsToGenerateComplexPropertyPaths = this.RequireRestrictionAnnotationsToGenerateComplexPropertyPaths,
                 ExpandDerivedTypesNavigationProperties = this.ExpandDerivedTypesNavigationProperties,
                 CustomXMLAttributesMapping = this.CustomXMLAttributesMapping,
+                CustomHttpMethodLinkRelMapping = this.CustomHttpMethodLinkRelMapping,
                 AppendBoundOperationsOnDerivedTypeCastSegments = this.AppendBoundOperationsOnDerivedTypeCastSegments,
                 UseSuccessStatusCodeRange = this.UseSuccessStatusCodeRange
             };

src/Microsoft.OpenApi.OData.Reader/Operation/EdmActionOperationHandler.cs

@@ -7,7 +7,9 @@
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.OData.Common;
+using Microsoft.OpenApi.OData.Edm;
 using Microsoft.OpenApi.OData.Generator;
+using Microsoft.OpenApi.OData.Vocabulary.Capabilities;
 
 namespace Microsoft.OpenApi.OData.Operation
 {
@@ -19,6 +21,19 @@ internal class EdmActionOperationHandler : EdmOperationOperationHandler
         /// <inheritdoc/>
         public override OperationType OperationType => OperationType.Post;
 
+        /// <inheritdoc/>
+        protected override void SetBasicInfo(OpenApiOperation operation)
+        {
+            base.SetBasicInfo(operation);
+
+            // Description
+            var insertRestrictions = Context.Model.GetRecord<InsertRestrictionsType>(EdmOperation, CapabilitiesConstants.InsertRestrictions);
+            if (!string.IsNullOrWhiteSpace(insertRestrictions?.LongDescription))
+            {
+                operation.Description = insertRestrictions.LongDescription;
+            }
+        }
+
         /// <inheritdoc/>
         protected override void SetRequestBody(OpenApiOperation operation)
         {

src/Microsoft.OpenApi.OData.Reader/Operation/EdmFunctionOperationHandler.cs

@@ -7,6 +7,8 @@
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.OData.Common;
+using Microsoft.OpenApi.OData.Edm;
+using Microsoft.OpenApi.OData.Vocabulary.Capabilities;
 
 namespace Microsoft.OpenApi.OData.Operation
 {
@@ -23,6 +25,19 @@ internal class EdmFunctionOperationHandler : EdmOperationOperationHandler
         /// </summary>
         public IEdmFunction Function => EdmOperation as IEdmFunction;
 
+        /// <inheritdoc/>
+        protected override void SetBasicInfo(OpenApiOperation operation)
+        {
+            base.SetBasicInfo(operation);
+
+            // Description
+            var readRestrictions = Context.Model.GetRecord<ReadRestrictionsType>(EdmOperation, CapabilitiesConstants.ReadRestrictions);
+            if (!string.IsNullOrWhiteSpace(readRestrictions?.LongDescription))
+            {
+                operation.Description = readRestrictions.LongDescription;
+            }
+        }
+
         /// <inheritdoc/>
         protected override void SetExtensions(OpenApiOperation operation)
         {

src/Microsoft.OpenApi.OData.Reader/Operation/EdmOperationImportOperationHandler.cs

@@ -13,6 +13,7 @@
 using Microsoft.OpenApi.OData.Edm;
 using Microsoft.OpenApi.OData.Generator;
 using Microsoft.OpenApi.OData.Vocabulary.Capabilities;
+using Microsoft.OpenApi.OData.Vocabulary.Core;
 
 namespace Microsoft.OpenApi.OData.Operation
 {
@@ -152,5 +153,18 @@ internal static string PathAsString(IEnumerable<string> path)
         {
             return String.Join("/", path);
         }
+
+        /// <inheritdoc/>
+        protected override void SetExternalDocs(OpenApiOperation operation)
+        {
+            if (Context.Settings.ShowExternalDocs && Context.Model.GetLinkRecord(EdmOperationImport, CustomLinkRel) is Link externalDocs)
+            {
+                operation.ExternalDocs = new OpenApiExternalDocs()
+                {
+                    Description = CoreConstants.ExternalDocsDescription,
+                    Url = externalDocs.Href
+                };
+            }
+        }
     }
 }

src/Microsoft.OpenApi.OData.Reader/Operation/EdmOperationOperationHandler.cs

@@ -12,6 +12,7 @@
 using Microsoft.OpenApi.OData.Edm;
 using Microsoft.OpenApi.OData.Generator;
 using Microsoft.OpenApi.OData.Vocabulary.Capabilities;
+using Microsoft.OpenApi.OData.Vocabulary.Core;
 
 namespace Microsoft.OpenApi.OData.Operation
 {
@@ -42,9 +43,7 @@ internal abstract class EdmOperationOperationHandler : OperationHandler
 
         /// <inheritdoc/>
         protected override void Initialize(ODataContext context, ODataPath path)
-        {
-            base.Initialize(context, path);
-
+        { 
             // It's bound operation, the first segment must be the navigaiton source.
             ODataNavigationSourceSegment navigationSourceSegment = path.FirstSegment as ODataNavigationSourceSegment;
             NavigationSource = navigationSourceSegment.NavigationSource;
@@ -53,6 +52,8 @@ protected override void Initialize(ODataContext context, ODataPath path)
             EdmOperation = OperationSegment.Operation;
 
             HasTypeCast = path.Segments.Any(s => s is ODataTypeCastSegment);
+
+            base.Initialize(context, path);
         }
 
         /// <inheritdoc/>
@@ -198,5 +199,30 @@ protected override void AppendCustomParameters(OpenApiOperation operation)
                 AppendCustomParameters(operation, restriction.CustomQueryOptions, ParameterLocation.Query);
             }
         }
+
+        /// <inheritdoc/>
+        protected override void SetCustomLinkRelType()
+        {
+            if (Context.Settings.CustomHttpMethodLinkRelMapping != null && EdmOperation != null)
+            {
+                LinkRelKey key = EdmOperation.IsAction() ? LinkRelKey.Action : LinkRelKey.Function;
+                Context.Settings.CustomHttpMethodLinkRelMapping.TryGetValue(key, out string linkRelValue);
+                CustomLinkRel =  linkRelValue;
+            }
+        }
+
+
+    /// <inheritdoc/>
+    protected override void SetExternalDocs(OpenApiOperation operation)
+        {
+            if (Context.Settings.ShowExternalDocs && Context.Model.GetLinkRecord(EdmOperation, CustomLinkRel) is Link externalDocs)
+            {
+                operation.ExternalDocs = new OpenApiExternalDocs()
+                {
+                    Description = CoreConstants.ExternalDocsDescription,
+                    Url = externalDocs.Href
+                };
+            }
+        }
     }
 }

src/Microsoft.OpenApi.OData.Reader/Operation/EntitySetOperationHandler.cs

@@ -8,6 +8,7 @@
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.OData.Common;
 using Microsoft.OpenApi.OData.Edm;
+using Microsoft.OpenApi.OData.Vocabulary.Core;
 
 namespace Microsoft.OpenApi.OData.Operation
 {
@@ -56,5 +57,18 @@ protected override void SetExtensions(OpenApiOperation operation)
 
             base.SetExtensions(operation);
         }
+
+        /// <inheritdoc/>
+        protected override void SetExternalDocs(OpenApiOperation operation)
+        {
+            if (Context.Settings.ShowExternalDocs && Context.Model.GetLinkRecord(EntitySet, CustomLinkRel) is Link externalDocs)
+            {
+                operation.ExternalDocs = new OpenApiExternalDocs()
+                {
+                    Description = CoreConstants.ExternalDocsDescription,
+                    Url = externalDocs.Href
+                };
+            }
+        }
     }
 }

src/Microsoft.OpenApi.OData.Reader/Operation/MediaEntityOperationalHandler.cs

@@ -10,6 +10,7 @@
 using Microsoft.OpenApi.OData.Common;
 using Microsoft.OpenApi.OData.Edm;
 using Microsoft.OpenApi.OData.Vocabulary.Capabilities;
+using Microsoft.OpenApi.OData.Vocabulary.Core;
 using System.Collections.Generic;
 using System.Linq;
 
@@ -24,7 +25,7 @@ internal abstract class MediaEntityOperationalHandler : NavigationPropertyOperat
         /// Gets/Sets the NavigationSource segment
         /// </summary>
         protected ODataNavigationSourceSegment NavigationSourceSegment { get; private set; }
-
+    
         /// <summary>
         /// Gets/Sets flag indicating whether path is navigation property path
         /// </summary>
@@ -204,5 +205,18 @@ private IEdmNavigationProperty GetNavigationProperty(IEdmEntityType entityType,
         {
             return entityType.DeclaredNavigationProperties().FirstOrDefault(x => x.Name.Equals(identifier));
         }
+
+        protected override void SetExternalDocs(OpenApiOperation operation)
+        {
+            if (Context.Settings.ShowExternalDocs && IsNavigationPropertyPath &&
+                Context.Model.GetLinkRecord(NavigationProperty, CustomLinkRel) is Link externalDocs)
+            {
+                operation.ExternalDocs = new OpenApiExternalDocs()
+                {
+                    Description = CoreConstants.ExternalDocsDescription,
+                    Url = externalDocs.Href
+                };
+            }
+        }
     }
 }

src/Microsoft.OpenApi.OData.Reader/Operation/NavigationPropertyOperationHandler.cs

@@ -12,6 +12,7 @@
 using Microsoft.OpenApi.OData.Edm;
 using Microsoft.OpenApi.OData.Vocabulary;
 using Microsoft.OpenApi.OData.Vocabulary.Capabilities;
+using Microsoft.OpenApi.OData.Vocabulary.Core;
 
 namespace Microsoft.OpenApi.OData.Operation
 {
@@ -156,6 +157,19 @@ protected string GetOperationId(string prefix = null)
             return string.Join(".", items);
         }
 
+        /// <inheritdoc/>
+        protected override void SetExternalDocs(OpenApiOperation operation)
+        {
+            if (Context.Settings.ShowExternalDocs && Context.Model.GetLinkRecord(NavigationProperty, CustomLinkRel) is Link externalDocs)
+            {
+                operation.ExternalDocs = new OpenApiExternalDocs()
+                { 
+                    Description = CoreConstants.ExternalDocsDescription, 
+                    Url = externalDocs.Href 
+                };
+            }
+        }
+
         /// <summary>
         /// Retrieves the CRUD restrictions annotations for the navigation property
         /// in context, given a capability annotation term.