adds descriptions for path items

src/Microsoft.OpenApi.OData.Reader/PathItem/DollarCountPathItemHandler.cs

@@ -21,5 +21,11 @@ protected override void SetOperations(OpenApiPathItem item)
         {
             AddOperation(item, OperationType.Get);
         }
+        /// <inheritdoc/>
+        protected override void SetBasicInfo(OpenApiPathItem pathItem)
+        {
+            base.SetBasicInfo(pathItem);
+            pathItem.Description = "Provides operations to count the resources in the collection.";
+        }
     }
 }

src/Microsoft.OpenApi.OData.Reader/PathItem/EntitySetPathItemHandler.cs

@@ -48,5 +48,11 @@ protected override void Initialize(ODataContext context, ODataPath path)
             ODataNavigationSourceSegment navigationSourceSegment = path.FirstSegment as ODataNavigationSourceSegment;
             EntitySet = navigationSourceSegment.NavigationSource as IEdmEntitySet;
         }
+        /// <inheritdoc/>
+        protected override void SetBasicInfo(OpenApiPathItem pathItem)
+        {
+            base.SetBasicInfo(pathItem);
+            pathItem.Description = $"Provides operations to manage the collection of {EntitySet.EntityType().Name} entities.";
+        }
     }
 }

src/Microsoft.OpenApi.OData.Reader/PathItem/MediaEntityPathItemHandler.cs

@@ -66,5 +66,11 @@ protected override void Initialize(ODataContext context, ODataPath path)
                 Singleton = navigationSourceSegment.NavigationSource as IEdmSingleton;
             }
         }
+        /// <inheritdoc/>
+        protected override void SetBasicInfo(OpenApiPathItem pathItem)
+        {
+            base.SetBasicInfo(pathItem);
+            pathItem.Description = $"Provides operations to manage the media for the {(EntitySet?.EntityType() ?? Singleton?.EntityType()).Name} entity.";
+        }
     }
 }

src/Microsoft.OpenApi.OData.Reader/PathItem/MetadataPathItemHandler.cs

@@ -21,5 +21,11 @@ protected override void SetOperations(OpenApiPathItem item)
         {
             AddOperation(item, OperationType.Get);
         }
+        /// <inheritdoc/>
+        protected override void SetBasicInfo(OpenApiPathItem pathItem)
+        {
+            base.SetBasicInfo(pathItem);
+            pathItem.Description = "Provides operations to obtain the service metadata.";
+        }
     }
 }

src/Microsoft.OpenApi.OData.Reader/PathItem/NavigationPropertyPathItemHandler.cs

@@ -246,5 +246,11 @@ protected override void SetExtensions(OpenApiPathItem item)
                 item.Extensions.Add(Constants.xMsDosGroupPath, array);
             }
         }
+        /// <inheritdoc/>
+        protected override void SetBasicInfo(OpenApiPathItem pathItem)
+        {
+            base.SetBasicInfo(pathItem);
+            pathItem.Description = $"Provides operations to manage the {NavigationProperty.Name} property of the {NavigationProperty.DeclaringType.FullTypeName()} entity.";
+        }
     }
 }

src/Microsoft.OpenApi.OData.Reader/PathItem/OperationImportPathItemHandler.cs

@@ -58,5 +58,11 @@ protected override void Initialize(ODataContext context, ODataPath path)
             ODataOperationImportSegment operationImportSegment = path.FirstSegment as ODataOperationImportSegment;
             EdmOperationImport = operationImportSegment.OperationImport;
         }
+        /// <inheritdoc/>
+        protected override void SetBasicInfo(OpenApiPathItem pathItem)
+        {
+            base.SetBasicInfo(pathItem);
+            pathItem.Description = $"Provides operations to call the {EdmOperationImport.Name} method.";
+        }
     }
 }

src/Microsoft.OpenApi.OData.Reader/PathItem/OperationPathItemHandler.cs

@@ -94,5 +94,11 @@ protected override void SetExtensions(OpenApiPathItem item)
                 item.Extensions.Add(Constants.xMsDosGroupPath, array);
             }
         }
+        /// <inheritdoc/>
+        protected override void SetBasicInfo(OpenApiPathItem pathItem)
+        {
+            base.SetBasicInfo(pathItem);
+            pathItem.Description = $"Provides operations to call the {EdmOperation.Name} method.";
+        }
     }
 }

src/Microsoft.OpenApi.OData.Reader/PathItem/PathItemHandler.cs

@@ -41,14 +41,22 @@ public virtual OpenApiPathItem CreatePathItem(ODataContext context, ODataPath pa
 
             Initialize(context, path);
 
-            OpenApiPathItem item = new OpenApiPathItem();
+            OpenApiPathItem item = new();
+
+            SetBasicInfo(item);
 
             SetOperations(item);
 
             SetExtensions(item);
 
             return item;
         }
+        /// <summary>
+        /// Set the basic information for <see cref="OpenApiPathItem"/>.
+        /// </summary>
+        /// <param name="pathItem">The <see cref="OpenApiPathItem"/>.</param>
+        protected virtual void SetBasicInfo(OpenApiPathItem pathItem)
+        { }
 
         /// <summary>
         /// Set the operation for the path item.

src/Microsoft.OpenApi.OData.Reader/PathItem/RefPathItemHandler.cs

@@ -137,5 +137,11 @@ protected override void Initialize(ODataContext context, ODataPath path)
 
             NavigationProperty = path.OfType<ODataNavigationPropertySegment>().Last().NavigationProperty;
         }
+        /// <inheritdoc/>
+        protected override void SetBasicInfo(OpenApiPathItem pathItem)
+        {
+            base.SetBasicInfo(pathItem);
+            pathItem.Description = $"Provides operations to manage the collection of {NavigationSource?.EntityType().Name ?? NavigationProperty?.Type.ShortQualifiedName()} entities.";
+        }
     }
 }

src/Microsoft.OpenApi.OData.Reader/PathItem/SingletonPathItemHandler.cs

@@ -49,5 +49,11 @@ protected override void Initialize(ODataContext context, ODataPath path)
             ODataNavigationSourceSegment navigationSourceSegment = path.FirstSegment as ODataNavigationSourceSegment;
             Singleton = navigationSourceSegment.NavigationSource as IEdmSingleton;
         }
+        /// <inheritdoc/>
+        protected override void SetBasicInfo(OpenApiPathItem pathItem)
+        {
+            base.SetBasicInfo(pathItem);
+            pathItem.Description = $"Provides operations to manage the {Singleton.EntityType().Name} singleton.";
+        }
     }
 }

test/Microsoft.OpenAPI.OData.Reader.Tests/PathItem/EntityPathItemHandlerTests.cs

@@ -99,6 +99,7 @@ public void CreateEntityPathItemReturnsCorrectPathItemWithReferences()
             Assert.Equal(3, pathItem.Operations.Count);
             Assert.Equal(new OperationType[] { OperationType.Get, OperationType.Patch, OperationType.Delete },
                 pathItem.Operations.Select(o => o.Key));
+            Assert.NotEmpty(pathItem.Description);
         }
 
         [Theory]

test/Microsoft.OpenAPI.OData.Reader.Tests/PathItem/EntitySetPathItemHandlerTests.cs

@@ -77,6 +77,7 @@ public void CreateEntitySetPathItemReturnsCorrectPathItem()
             Assert.Equal(2, pathItem.Operations.Count);
             Assert.Equal(new OperationType[] { OperationType.Get, OperationType.Post },
                 pathItem.Operations.Select(o => o.Key));
+            Assert.NotEmpty(pathItem.Description);
         }
 
         [Theory]

test/Microsoft.OpenAPI.OData.Reader.Tests/PathItem/MediaEntityPathItemHandlerTests.cs

@@ -94,6 +94,7 @@ public void CreateMediaEntityPathItemReturnsCorrectItem()
                 pathItem.Operations.Select(o => o.Key));
             Assert.Equal(new OperationType[] { OperationType.Get, OperationType.Put },
                 pathItem2.Operations.Select(o => o.Key));
+            Assert.NotEmpty(pathItem.Description);
         }
 
         [Theory]

test/Microsoft.OpenAPI.OData.Reader.Tests/PathItem/NavigationPropertyPathItemHandlerTests.cs

@@ -92,6 +92,7 @@ public void CreateCollectionNavigationPropertyPathItemReturnsCorrectPathItem(boo
             Assert.NotNull(pathItem.Operations);
             Assert.NotEmpty(pathItem.Operations);
             Assert.Equal(expected, pathItem.Operations.Select(o => o.Key));
+            Assert.NotEmpty(pathItem.Description);
         }
 
         [Theory]

test/Microsoft.OpenAPI.OData.Reader.Tests/PathItem/OperationImportPathItemHandlerTests.cs

@@ -78,6 +78,7 @@ public void CreatePathItemForOperationImportReturnsCorrectPathItem(string operat
             var operationKeyValue = Assert.Single(pathItem.Operations);
             Assert.Equal(operationType, operationKeyValue.Key);
             Assert.NotNull(operationKeyValue.Value);
+            Assert.NotEmpty(pathItem.Description);
         }
 
         [Theory]

test/Microsoft.OpenAPI.OData.Reader.Tests/PathItem/OperationPathItemHandlerTests.cs

@@ -82,6 +82,7 @@ public void CreatePathItemForOperationReturnsCorrectPathItem(string operationNam
             Assert.NotNull(operationKeyValue.Value);
 
             Assert.Equal(expectSummary, operationKeyValue.Value.Summary);
+            Assert.NotEmpty(pathItem.Description);
         }
     }
 }

test/Microsoft.OpenAPI.OData.Reader.Tests/PathItem/RefPathItemHandlerTests.cs

@@ -101,6 +101,7 @@ public void CreateNavigationPropertyRefPathItemReturnsCorrectPathItem(bool colle
             Assert.NotNull(pathItem.Operations);
             Assert.NotEmpty(pathItem.Operations);
             Assert.Equal(expected, pathItem.Operations.Select(o => o.Key));
+            Assert.NotEmpty(pathItem.Description);
         }
 
         public static IEdmModel GetEdmModel(string annotation)

test/Microsoft.OpenAPI.OData.Reader.Tests/PathItem/SingletonPathItemHandlerTests.cs

@@ -77,6 +77,7 @@ public void CreateSingletonPathItemReturnsCorrectPathItem()
             Assert.Equal(2, pathItem.Operations.Count);
             Assert.Equal(new OperationType[] { OperationType.Get, OperationType.Patch },
                 pathItem.Operations.Select(o => o.Key));
+            Assert.NotEmpty(pathItem.Description);
         }
 
         [Theory]

test/Microsoft.OpenAPI.OData.Reader.Tests/Resources/Basic.OpenApi.V2.json

@@ -130,7 +130,8 @@
           }
         },
         "x-ms-docs-operation-type": "operation"
-      }
+      },
+      "x-description": "Provides operations to manage the collection of City entities."
     },
     "/City({Name})": {
       "get": {
@@ -258,7 +259,8 @@
           }
         },
         "x-ms-docs-operation-type": "operation"
-      }
+      },
+      "x-description": "Provides operations to manage the collection of City entities."
     },
     "/City/$count": {
       "get": {
@@ -278,7 +280,8 @@
             "$ref": "#/responses/error"
           }
         }
-      }
+      },
+      "x-description": "Provides operations to count the resources in the collection."
     },
     "/CountryOrRegion": {
       "get": {
@@ -400,7 +403,8 @@
           }
         },
         "x-ms-docs-operation-type": "operation"
-      }
+      },
+      "x-description": "Provides operations to manage the collection of CountryOrRegion entities."
     },
     "/CountryOrRegion({Name})": {
       "get": {
@@ -528,7 +532,8 @@
           }
         },
         "x-ms-docs-operation-type": "operation"
-      }
+      },
+      "x-description": "Provides operations to manage the collection of CountryOrRegion entities."
     },
     "/CountryOrRegion/$count": {
       "get": {
@@ -548,7 +553,8 @@
             "$ref": "#/responses/error"
           }
         }
-      }
+      },
+      "x-description": "Provides operations to count the resources in the collection."
     },
     "/Me": {
       "get": {
@@ -631,7 +637,8 @@
           }
         },
         "x-ms-docs-operation-type": "operation"
-      }
+      },
+      "x-description": "Provides operations to manage the Person singleton."
     },
     "/People": {
       "get": {
@@ -764,7 +771,8 @@
           }
         },
         "x-ms-docs-operation-type": "operation"
-      }
+      },
+      "x-description": "Provides operations to manage the collection of Person entities."
     },
     "/People({UserName})": {
       "get": {
@@ -895,7 +903,8 @@
           }
         },
         "x-ms-docs-operation-type": "operation"
-      }
+      },
+      "x-description": "Provides operations to manage the collection of Person entities."
     },
     "/People/$count": {
       "get": {
@@ -915,7 +924,8 @@
             "$ref": "#/responses/error"
           }
         }
-      }
+      },
+      "x-description": "Provides operations to count the resources in the collection."
     }
   },
   "definitions": {

test/Microsoft.OpenAPI.OData.Reader.Tests/Resources/Basic.OpenApi.V2.yaml

@@ -83,6 +83,7 @@ paths:
         default:
           $ref: '#/responses/error'
       x-ms-docs-operation-type: operation
+    x-description: Provides operations to manage the collection of City entities.
   '/City({Name})':
     get:
       tags:
@@ -170,6 +171,7 @@ paths:
         default:
           $ref: '#/responses/error'
       x-ms-docs-operation-type: operation
+    x-description: Provides operations to manage the collection of City entities.
   /City/$count:
     get:
       summary: Get the number of the resource
@@ -183,6 +185,7 @@ paths:
             $ref: '#/definitions/ODataCountResponse'
         default:
           $ref: '#/responses/error'
+    x-description: Provides operations to count the resources in the collection.
   /CountryOrRegion:
     get:
       tags:
@@ -259,6 +262,7 @@ paths:
         default:
           $ref: '#/responses/error'
       x-ms-docs-operation-type: operation
+    x-description: Provides operations to manage the collection of CountryOrRegion entities.
   '/CountryOrRegion({Name})':
     get:
       tags:
@@ -346,6 +350,7 @@ paths:
         default:
           $ref: '#/responses/error'
       x-ms-docs-operation-type: operation
+    x-description: Provides operations to manage the collection of CountryOrRegion entities.
   /CountryOrRegion/$count:
     get:
       summary: Get the number of the resource
@@ -359,6 +364,7 @@ paths:
             $ref: '#/definitions/ODataCountResponse'
         default:
           $ref: '#/responses/error'
+    x-description: Provides operations to count the resources in the collection.
   /Me:
     get:
       tags:
@@ -415,6 +421,7 @@ paths:
         default:
           $ref: '#/responses/error'
       x-ms-docs-operation-type: operation
+    x-description: Provides operations to manage the Person singleton.
   /People:
     get:
       tags:
@@ -502,6 +509,7 @@ paths:
         default:
           $ref: '#/responses/error'
       x-ms-docs-operation-type: operation
+    x-description: Provides operations to manage the collection of Person entities.
   '/People({UserName})':
     get:
       tags:
@@ -592,6 +600,7 @@ paths:
         default:
           $ref: '#/responses/error'
       x-ms-docs-operation-type: operation
+    x-description: Provides operations to manage the collection of Person entities.
   /People/$count:
     get:
       summary: Get the number of the resource
@@ -605,6 +614,7 @@ paths:
             $ref: '#/definitions/ODataCountResponse'
         default:
           $ref: '#/responses/error'
+    x-description: Provides operations to count the resources in the collection.
 definitions:
   DefaultNs.Color:
     title: Color