Summaries and Descriptions Mapping (#206)

* Handle Summaries and Descriptions from *Restrictions annotations in csdl. Default to a placeholder if descriptions are missing. Map Summary to Description. Map Description to LongDescription. * make differentiating changes to test data. * Differentiate summary from description. * Remove summary handling. * Update tests. * Use explicity typing. * Singleton. * Update CRUD operations summaries and descriptions * Corrections. * update test data. * Update some CRUD operations summaries and descriptions * Update tests Co-authored-by: George <[email protected]> Co-authored-by: Irvine Sunday <[email protected]> Co-authored-by: Irvine Sunday <[email protected]>
microsoft · Apr 7, 2022 · 0304edb · 0304edb
1 parent ac9c93e
commit 0304edb
Show file tree

Hide file tree

Showing 43 changed files with 291 additions and 292 deletions.
diff --git a/src/Microsoft.OpenApi.OData.Reader/Operation/ComplexPropertyGetOperationHandler.cs b/src/Microsoft.OpenApi.OData.Reader/Operation/ComplexPropertyGetOperationHandler.cs
@@ -35,9 +35,6 @@ protected override void Initialize(ODataContext context, ODataPath path)
     /// <inheritdoc/>
     protected override void SetBasicInfo(OpenApiOperation operation)
     {
-        // Summary
-        operation.Summary = $"Get {ComplexPropertySegment.Property.Name} property value";
-
         // OperationId
         if (Context.Settings.EnableOperationId)
         {
@@ -46,8 +43,10 @@ protected override void SetBasicInfo(OpenApiOperation operation)
             operation.OperationId = ComplexPropertySegment.Property.Name + "." + typeName + listOrGet + Utils.UpperFirstChar(typeName);
         }
 
-        // Description
-        operation.Description = ReadRestrictions?.Description ?? Context.Model.GetDescriptionAnnotation(ComplexPropertySegment.Property);
+        // Summary and Description
+        string placeHolder = $"Get {ComplexPropertySegment.Property.Name} property value";
+        operation.Summary = ReadRestrictions?.Description ?? placeHolder;
+        operation.Description = ReadRestrictions?.LongDescription ?? Context.Model.GetDescriptionAnnotation(ComplexPropertySegment.Property);
 
         base.SetBasicInfo(operation);
     }

diff --git a/src/Microsoft.OpenApi.OData.Reader/Operation/ComplexPropertyPostOperationHandler.cs b/src/Microsoft.OpenApi.OData.Reader/Operation/ComplexPropertyPostOperationHandler.cs
@@ -21,7 +21,7 @@ internal class ComplexPropertyPostOperationHandler : ComplexPropertyBaseOperatio
     protected override void Initialize(ODataContext context, ODataPath path)
     {
         base.Initialize(context, path);
-        if(!ComplexPropertySegment.Property.Type.IsCollection())
+        if (!ComplexPropertySegment.Property.Type.IsCollection())
         {
             throw new InvalidOperationException("OData conventions do not support POSTing to a complex property that is not a collection.");
         }
@@ -39,18 +39,17 @@ protected override void Initialize(ODataContext context, ODataPath path)
     /// <inheritdoc/>
     protected override void SetBasicInfo(OpenApiOperation operation)
     {
-        // Summary
-        operation.Summary = $"Sets a new value for the collection of {ComplexPropertySegment.ComplexType.Name}.";
-
         // OperationId
         if (Context.Settings.EnableOperationId)
         {
             string typeName = ComplexPropertySegment.ComplexType.Name;
             operation.OperationId = ComplexPropertySegment.Property.Name + "." + typeName + ".Set" + Utils.UpperFirstChar(typeName);
         }
 
-        // Description
-        operation.Description = InsertRestrictions?.Description;
+        // Summary and Description
+        string placeHolder = $"Sets a new value for the collection of {ComplexPropertySegment.ComplexType.Name}.";
+        operation.Summary = InsertRestrictions?.Description ?? placeHolder;
+        operation.Description = InsertRestrictions?.LongDescription;
 
         base.SetBasicInfo(operation);
     }

diff --git a/src/Microsoft.OpenApi.OData.Reader/Operation/ComplexPropertyUpdateOperationHandler.cs b/src/Microsoft.OpenApi.OData.Reader/Operation/ComplexPropertyUpdateOperationHandler.cs
@@ -31,11 +31,10 @@ protected override void Initialize(ODataContext context, ODataPath path)
     /// <inheritdoc/>
     protected override void SetBasicInfo(OpenApiOperation operation)
     {
-        // Summary
-        operation.Summary = $"Update property {ComplexPropertySegment.Property.Name} value.";
-
-        // Description
-        operation.Description = UpdateRestrictions?.Description;
+        // Summary and Description
+        string placeHolder = $"Update property {ComplexPropertySegment.Property.Name} value.";
+        operation.Summary = UpdateRestrictions?.Description ?? placeHolder;
+        operation.Description = UpdateRestrictions?.LongDescription;
 
         // OperationId
         if (Context.Settings.EnableOperationId)

diff --git a/src/Microsoft.OpenApi.OData.Reader/Operation/EntityDeleteOperationHandler.cs b/src/Microsoft.OpenApi.OData.Reader/Operation/EntityDeleteOperationHandler.cs
@@ -38,13 +38,12 @@ protected override void Initialize(ODataContext context, ODataPath path)
         /// <inheritdoc/>
         protected override void SetBasicInfo(OpenApiOperation operation)
         {
-            // Summary
-            operation.Summary = "Delete entity from " + EntitySet.Name;
-
             IEdmEntityType entityType = EntitySet.EntityType();
 
             // Description
-            operation.Description = DeleteRestrictions?.Description; 
+            string placeHolder = "Delete entity from " + EntitySet.Name;
+            operation.Summary = DeleteRestrictions?.Description ?? placeHolder;
+            operation.Description = DeleteRestrictions?.LongDescription;
 
             // OperationId
             if (Context.Settings.EnableOperationId)

diff --git a/src/Microsoft.OpenApi.OData.Reader/Operation/EntityGetOperationHandler.cs b/src/Microsoft.OpenApi.OData.Reader/Operation/EntityGetOperationHandler.cs
@@ -39,13 +39,12 @@ protected override void Initialize(ODataContext context, ODataPath path)
         /// <inheritdoc/>
         protected override void SetBasicInfo(OpenApiOperation operation)
         {
-            // Summary
-            operation.Summary = "Get entity from " + EntitySet.Name + " by key";
-
             IEdmEntityType entityType = EntitySet.EntityType();
 
             // Description
-            operation.Description = ReadRestrictions?.ReadByKeyRestrictions?.Description ?? Context.Model.GetDescriptionAnnotation(entityType);
+            string placeHolder = "Get entity from " + EntitySet.Name + " by key";
+            operation.Summary = ReadRestrictions?.ReadByKeyRestrictions?.Description ?? placeHolder;
+            operation.Description = ReadRestrictions?.ReadByKeyRestrictions?.LongDescription ?? Context.Model.GetDescriptionAnnotation(entityType);
 
             // OperationId
             if (Context.Settings.EnableOperationId)
@@ -132,7 +131,7 @@ protected override void SetResponses(OpenApiOperation operation)
         }
 
         protected override void SetSecurity(OpenApiOperation operation)
-        {            
+        {
             if (ReadRestrictions == null)
             {
                 return;

diff --git a/src/Microsoft.OpenApi.OData.Reader/Operation/EntitySetGetOperationHandler.cs b/src/Microsoft.OpenApi.OData.Reader/Operation/EntitySetGetOperationHandler.cs
@@ -40,18 +40,17 @@ protected override void Initialize(ODataContext context, ODataPath path)
         /// <inheritdoc/>
         protected override void SetBasicInfo(OpenApiOperation operation)
         {
-            // Summary
-            operation.Summary = "Get entities from " + EntitySet.Name;
+            // Summary and Descriptions
+            string placeHolder = "Get entities from " + EntitySet.Name;
+            operation.Summary = ReadRestrictions?.Description ?? placeHolder;
+            operation.Description = ReadRestrictions?.LongDescription ?? Context.Model.GetDescriptionAnnotation(EntitySet);
 
             // OperationId
             if (Context.Settings.EnableOperationId)
             {
                 string typeName = EntitySet.EntityType().Name;
                 operation.OperationId = EntitySet.Name + "." + typeName + ".List" + Utils.UpperFirstChar(typeName);
             }
-
-            // Description            
-            operation.Description = ReadRestrictions?.Description ?? Context.Model.GetDescriptionAnnotation(EntitySet);
         }
 
         protected override void SetExtensions(OpenApiOperation operation)

diff --git a/src/Microsoft.OpenApi.OData.Reader/Operation/EntitySetPostOperationHandler.cs b/src/Microsoft.OpenApi.OData.Reader/Operation/EntitySetPostOperationHandler.cs
@@ -39,18 +39,17 @@ protected override void Initialize(ODataContext context, ODataPath path)
         /// <inheritdoc/>
         protected override void SetBasicInfo(OpenApiOperation operation)
         {
-            // Summary
-            operation.Summary = "Add new entity to " + EntitySet.Name;
+            // Summary and Description
+            string placeHolder = "Add new entity to " + EntitySet.Name;
+            operation.Summary = InsertRestrictions?.Description ?? placeHolder;
+            operation.Description = InsertRestrictions?.LongDescription;
 
             // OperationId
             if (Context.Settings.EnableOperationId)
             {
                 string typeName = EntitySet.EntityType().Name;
                 operation.OperationId = EntitySet.Name + "." + typeName + ".Create" + Utils.UpperFirstChar(typeName);
             }
-
-            // Description
-            operation.Description = InsertRestrictions?.Description;
         }
 
         /// <inheritdoc/>

diff --git a/src/Microsoft.OpenApi.OData.Reader/Operation/EntityUpdateOperationHandler.cs b/src/Microsoft.OpenApi.OData.Reader/Operation/EntityUpdateOperationHandler.cs
@@ -34,13 +34,12 @@ protected override void Initialize(ODataContext context, ODataPath path)
         /// <inheritdoc/>
         protected override void SetBasicInfo(OpenApiOperation operation)
         {
-            // Summary
-            operation.Summary = "Update entity in " + EntitySet.Name;
-
             IEdmEntityType entityType = EntitySet.EntityType();
 
-            // Description
-            operation.Description = UpdateRestrictions?.Description;
+            // Summary and Description
+            string placeHolder = "Update entity in " + EntitySet.Name;
+            operation.Summary = UpdateRestrictions?.Description ?? placeHolder;
+            operation.Description = UpdateRestrictions?.LongDescription;
 
             // OperationId
             if (Context.Settings.EnableOperationId)

diff --git a/src/Microsoft.OpenApi.OData.Reader/Operation/NavigationPropertyDeleteOperationHandler.cs b/src/Microsoft.OpenApi.OData.Reader/Operation/NavigationPropertyDeleteOperationHandler.cs
@@ -24,18 +24,17 @@ internal class NavigationPropertyDeleteOperationHandler : NavigationPropertyOper
         /// <inheritdoc/>
         protected override void SetBasicInfo(OpenApiOperation operation)
         {
-            // Summary
-            operation.Summary = "Delete navigation property " + NavigationProperty.Name + " for " + NavigationSource.Name;
+            // Summary and Description
+            string placeHolder = "Delete navigation property " + NavigationProperty.Name + " for " + NavigationSource.Name;
+            operation.Summary = Restriction?.DeleteRestrictions?.Description ?? placeHolder;
+            operation.Description = Restriction?.DeleteRestrictions?.LongDescription;
 
             // OperationId
             if (Context.Settings.EnableOperationId)
             {
                 string prefix = "Delete";
                 operation.OperationId = GetOperationId(prefix);
-            }
-
-            // Description
-            operation.Description = Restriction?.DeleteRestrictions?.Description;
+            }            
 
             base.SetBasicInfo(operation);
         }

diff --git a/src/Microsoft.OpenApi.OData.Reader/Operation/NavigationPropertyGetOperationHandler.cs b/src/Microsoft.OpenApi.OData.Reader/Operation/NavigationPropertyGetOperationHandler.cs
@@ -27,8 +27,12 @@ internal class NavigationPropertyGetOperationHandler : NavigationPropertyOperati
         /// <inheritdoc/>
         protected override void SetBasicInfo(OpenApiOperation operation)
         {
-            // Summary
-            operation.Summary = "Get " + NavigationProperty.Name + " from " + NavigationSource.Name;
+            // Summary and Description
+            ReadRestrictionsType readRestriction = Restriction?.ReadRestrictions;
+            string placeHolder = "Get " + NavigationProperty.Name + " from " + NavigationSource.Name;
+            operation.Summary = (LastSegmentIsKeySegment ? readRestriction?.ReadByKeyRestrictions?.Description : readRestriction?.Description) ?? placeHolder;    
+            operation.Description = (LastSegmentIsKeySegment ? readRestriction?.ReadByKeyRestrictions?.LongDescription : readRestriction?.LongDescription)
+                ?? Context.Model.GetDescriptionAnnotation(NavigationProperty);
 
             // OperationId
             if (Context.Settings.EnableOperationId)
@@ -41,12 +45,7 @@ protected override void SetBasicInfo(OpenApiOperation operation)
 
                 operation.OperationId = GetOperationId(prefix);
             }
-
-            // Description
-            ReadRestrictionsType readRestriction = Restriction?.ReadRestrictions;
-            operation.Description = (LastSegmentIsKeySegment ? readRestriction?.ReadByKeyRestrictions?.Description : readRestriction?.Description)
-                ?? Context.Model.GetDescriptionAnnotation(NavigationProperty);
-
+
             base.SetBasicInfo(operation);
         }
 

diff --git a/src/Microsoft.OpenApi.OData.Reader/Operation/NavigationPropertyPostOperationHandler.cs b/src/Microsoft.OpenApi.OData.Reader/Operation/NavigationPropertyPostOperationHandler.cs
@@ -25,8 +25,10 @@ internal class NavigationPropertyPostOperationHandler : NavigationPropertyOperat
         /// <inheritdoc/>
         protected override void SetBasicInfo(OpenApiOperation operation)
         {
-            // Summary
-            operation.Summary = "Create new navigation property to " + NavigationProperty.Name + " for " + NavigationSource.Name;
+            // Summary and Description
+            string placeHolder = "Create new navigation property to " + NavigationProperty.Name + " for " + NavigationSource.Name;
+            operation.Summary = Restriction?.InsertRestrictions?.Description ?? placeHolder;
+            operation.Description = Restriction?.InsertRestrictions?.LongDescription;
 
             // OperationId
             if (Context.Settings.EnableOperationId)
@@ -35,9 +37,6 @@ protected override void SetBasicInfo(OpenApiOperation operation)
                 operation.OperationId = GetOperationId(prefix);
             }
 
-            // Description
-            operation.Description = Restriction?.InsertRestrictions?.Description;
-
             base.SetBasicInfo(operation);
         }
 

diff --git a/src/Microsoft.OpenApi.OData.Reader/Operation/NavigationPropertyUpdateOperationHandler.cs b/src/Microsoft.OpenApi.OData.Reader/Operation/NavigationPropertyUpdateOperationHandler.cs
@@ -22,8 +22,10 @@ internal abstract class NavigationPropertyUpdateOperationHandler : NavigationPro
         /// <inheritdoc/>
         protected override void SetBasicInfo(OpenApiOperation operation)
         {
-            // Summary
-            operation.Summary = "Update the navigation property " + NavigationProperty.Name + " in " + NavigationSource.Name;
+            // Summary and Description
+            string placeHolder = "Update the navigation property " + NavigationProperty.Name + " in " + NavigationSource.Name;
+            operation.Summary = Restriction?.UpdateRestrictions?.Description ?? placeHolder;
+            operation.Description = Restriction?.UpdateRestrictions?.LongDescription;
 
             // OperationId
             if (Context.Settings.EnableOperationId)
@@ -32,9 +34,6 @@ protected override void SetBasicInfo(OpenApiOperation operation)
                 operation.OperationId = GetOperationId(prefix);
             }
 
-            // Description
-            operation.Description = Restriction?.UpdateRestrictions?.Description;
-
             base.SetBasicInfo(operation);
         }
 

diff --git a/src/Microsoft.OpenApi.OData.Reader/Operation/RefDeleteOperationHandler.cs b/src/Microsoft.OpenApi.OData.Reader/Operation/RefDeleteOperationHandler.cs
@@ -22,18 +22,17 @@ internal class RefDeleteOperationHandler : NavigationPropertyOperationHandler
         /// <inheritdoc/>
         protected override void SetBasicInfo(OpenApiOperation operation)
         {
-            // Summary
-            operation.Summary = "Delete ref of navigation property " + NavigationProperty.Name + " for " + NavigationSource.Name;
+            // Summary and Description
+            string placeHolder = "Delete ref of navigation property " + NavigationProperty.Name + " for " + NavigationSource.Name;
+            operation.Summary = Restriction?.DeleteRestrictions?.Description ?? placeHolder;
+            operation.Description = Restriction?.DeleteRestrictions?.LongDescription;
 
             // OperationId
             if (Context.Settings.EnableOperationId)
             {
                 string prefix = "DeleteRef";
                 operation.OperationId = GetOperationId(prefix);
-            }
-
-            // Description
-            operation.Description = Restriction?.DeleteRestrictions?.Description;
+            }            
         }
 
         /// <inheritdoc/>

diff --git a/src/Microsoft.OpenApi.OData.Reader/Operation/RefGetOperationHandler.cs b/src/Microsoft.OpenApi.OData.Reader/Operation/RefGetOperationHandler.cs
@@ -25,8 +25,12 @@ internal class RefGetOperationHandler : NavigationPropertyOperationHandler
         /// <inheritdoc/>
         protected override void SetBasicInfo(OpenApiOperation operation)
         {
-            // Summary
-            operation.Summary = "Get ref of " + NavigationProperty.Name + " from " + NavigationSource.Name;
+            // Summary and Description
+            ReadRestrictionsType readRestriction = Restriction?.ReadRestrictions;
+            string placeHolder = "Get ref of " + NavigationProperty.Name + " from " + NavigationSource.Name;
+            operation.Summary = (LastSegmentIsKeySegment ? readRestriction?.ReadByKeyRestrictions?.Description : readRestriction?.Description) ?? placeHolder;
+            operation.Description = (LastSegmentIsKeySegment ? readRestriction?.ReadByKeyRestrictions?.LongDescription : readRestriction?.LongDescription)
+                ?? Context.Model.GetDescriptionAnnotation(NavigationProperty);
 
             // OperationId
             if (Context.Settings.EnableOperationId)
@@ -39,11 +43,6 @@ protected override void SetBasicInfo(OpenApiOperation operation)
 
                 operation.OperationId = GetOperationId(prefix);
             }
-
-            // Description
-            ReadRestrictionsType readRestriction = Restriction?.ReadRestrictions;
-            operation.Description = (LastSegmentIsKeySegment ? readRestriction?.ReadByKeyRestrictions?.Description : readRestriction?.Description)
-                ?? Context.Model.GetDescriptionAnnotation(NavigationProperty);
         }
 
         protected override void SetExtensions(OpenApiOperation operation)

diff --git a/src/Microsoft.OpenApi.OData.Reader/Operation/RefPostOperationHandler.cs b/src/Microsoft.OpenApi.OData.Reader/Operation/RefPostOperationHandler.cs
@@ -22,8 +22,10 @@ internal class RefPostOperationHandler : NavigationPropertyOperationHandler
         /// <inheritdoc/>
         protected override void SetBasicInfo(OpenApiOperation operation)
         {
-            // Summary
-            operation.Summary = "Create new navigation property ref to " + NavigationProperty.Name + " for " + NavigationSource.Name;
+            // Summary and Description
+            string placeHolder = "Create new navigation property ref to " + NavigationProperty.Name + " for " + NavigationSource.Name;
+            operation.Summary = Restriction?.InsertRestrictions?.Description ?? placeHolder;
+            operation.Description = Restriction?.InsertRestrictions?.LongDescription;
 
             // OperationId
             if (Context.Settings.EnableOperationId)
@@ -32,8 +34,7 @@ protected override void SetBasicInfo(OpenApiOperation operation)
                 operation.OperationId = GetOperationId(prefix);
             }
 
-            // Description
-            operation.Description = Restriction?.InsertRestrictions?.Description;
+
         }
 
         /// <inheritdoc/>

diff --git a/src/Microsoft.OpenApi.OData.Reader/Operation/RefPutOperationHandler.cs b/src/Microsoft.OpenApi.OData.Reader/Operation/RefPutOperationHandler.cs
@@ -22,17 +22,17 @@ internal class RefPutOperationHandler : NavigationPropertyOperationHandler
         /// <inheritdoc/>
         protected override void SetBasicInfo(OpenApiOperation operation)
         {
-            // Summary
-            operation.Summary = "Update the ref of navigation property " + NavigationProperty.Name + " in " + NavigationSource.Name;
+            // Summary and Description
+            string placeHolder = "Update the ref of navigation property " + NavigationProperty.Name + " in " + NavigationSource.Name;
+            operation.Summary = Restriction?.UpdateRestrictions?.Description ?? placeHolder;
+            operation.Description = Restriction?.UpdateRestrictions?.LongDescription;
 
             // OperationId
             if (Context.Settings.EnableOperationId)
             {
                 string prefix = "UpdateRef";
                 operation.OperationId = GetOperationId(prefix);
             }
-
-            operation.Description = Restriction?.UpdateRestrictions?.Description;
         }
 
         /// <inheritdoc/>

diff --git a/src/Microsoft.OpenApi.OData.Reader/Operation/SingletonGetOperationHandler.cs b/src/Microsoft.OpenApi.OData.Reader/Operation/SingletonGetOperationHandler.cs
@@ -39,18 +39,17 @@ protected override void Initialize(ODataContext context, ODataPath path)
         /// <inheritdoc/>
         protected override void SetBasicInfo(OpenApiOperation operation)
         {
-            // Summary, this summary maybe update in the base function call.
-            operation.Summary = "Get " + Singleton.Name;
+            // Summary and Descriptions
+            string placeHolder = "Get " + Singleton.Name;
+            operation.Summary = ReadRestrictions?.Description ?? placeHolder;
+            operation.Description = ReadRestrictions?.LongDescription ?? Context.Model.GetDescriptionAnnotation(Singleton);
 
             // OperationId, it should be unique among all operations described in the API.
             if (Context.Settings.EnableOperationId)
             {
                 string typeName = Singleton.EntityType().Name;
                 operation.OperationId = Singleton.Name + "." + typeName + ".Get" + Utils.UpperFirstChar(typeName);
             }
-
-            // Description
-            operation.Description = ReadRestrictions?.Description ?? Context.Model.GetDescriptionAnnotation(Singleton);
         }
 
         /// <inheritdoc/>