Add webhooks property to the root document

src/Microsoft.OpenApi.Readers/ParsingContext.cs

@@ -65,7 +65,7 @@ internal OpenApiDocument Parse(YamlDocument yamlDocument)
                     this.Diagnostic.SpecificationVersion = OpenApiSpecVersion.OpenApi2_0;
                     break;
 
-                case string version when version.StartsWith("3.0"):
+                case string version when version.StartsWith("3.0") || version.StartsWith("3.1"):
                     VersionService = new OpenApiV3VersionService(Diagnostic);
                     doc = VersionService.LoadDocument(RootNode);
                     this.Diagnostic.SpecificationVersion = OpenApiSpecVersion.OpenApi3_0;

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

@@ -1,10 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license. 
 
-using System.Collections.Generic;
-using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Extensions;
-using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Readers.ParseNodes;
 
@@ -26,6 +23,7 @@ internal static partial class OpenApiV3Deserializer
             {"info", (o, n) => o.Info = LoadInfo(n)},
             {"servers", (o, n) => o.Servers = n.CreateList(LoadServer)},
             {"paths", (o, n) => o.Paths = LoadPaths(n)},
+            {"webhooks", (o, n) => o.Webhooks = n.CreateMapWithReference(ReferenceType.PathItem, LoadPathItem)},
             {"components", (o, n) => o.Components = LoadComponents(n)},
             {"tags", (o, n) => {o.Tags = n.CreateList(LoadTag);
                 foreach (var tag in o.Tags)

src/Microsoft.OpenApi/Models/OpenApiConstants.cs

@@ -20,6 +20,11 @@ public static class OpenApiConstants
         /// </summary>
         public const string Info = "info";
 
+        /// <summary>
+        /// Field: Webhooks
+        /// </summary>
+        public const string Webhooks = "webhooks";
+
         /// <summary>
         /// Field: Title
         /// </summary>

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

@@ -39,6 +39,13 @@ public class OpenApiDocument : IOpenApiSerializable, IOpenApiExtensible
         /// </summary>
         public OpenApiPaths Paths { get; set; }
 
+        /// <summary>
+        /// The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement.
+        /// A map of requests initiated other than by an API call, for example by an out of band registration. 
+        /// The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses
+        /// </summary>
+        public IDictionary<string, OpenApiPathItem> Webhooks { get; set; } = new Dictionary<string, OpenApiPathItem>();
+
         /// <summary>
         /// An element to hold various schemas for the specification.
         /// </summary>
@@ -84,6 +91,7 @@ public OpenApiDocument(OpenApiDocument document)
             Info = document?.Info != null ? new(document?.Info) : null;
             Servers = document?.Servers != null ? new List<OpenApiServer>(document.Servers) : null;
             Paths = document?.Paths != null ? new(document?.Paths) : null;
+            Webhooks = document?.Webhooks != null ? new Dictionary<string, OpenApiPathItem>(document.Webhooks) : null;
             Components = document?.Components != null ? new(document?.Components) : null;
             SecurityRequirements = document?.SecurityRequirements != null ? new List<OpenApiSecurityRequirement>(document.SecurityRequirements) : null;
             Tags = document?.Tags != null ? new List<OpenApiTag>(document.Tags) : null;
@@ -115,6 +123,24 @@ public void SerializeAsV3(IOpenApiWriter writer)
             // paths
             writer.WriteRequiredObject(OpenApiConstants.Paths, Paths, (w, p) => p.SerializeAsV3(w));
 
+            // webhooks
+            writer.WriteOptionalMap(
+                OpenApiConstants.Webhooks,
+                Webhooks,
+                (w, key, component) =>
+                {
+                    if (component.Reference != null &&
+                        component.Reference.Type == ReferenceType.Schema &&
+                        component.Reference.Id == key)
+                    {
+                        component.SerializeAsV3WithoutReference(w);
+                    }
+                    else
+                    {
+                        component.SerializeAsV3(w);
+                    }
+                });
+
             // components
             writer.WriteOptionalObject(OpenApiConstants.Components, Components, (w, c) => c.SerializeAsV3(w));
 

src/Microsoft.OpenApi/Models/ReferenceType.cs

@@ -58,6 +58,11 @@ public enum ReferenceType
         /// <summary>
         /// Tags item.
         /// </summary>
-        [Display("tags")] Tag
+        [Display("tags")] Tag,
+
+        /// <summary>
+        /// Path item.
+        /// </summary>
+        [Display("pathItem")] PathItem,
     }
 }

src/Microsoft.OpenApi/Services/OpenApiVisitorBase.cs

@@ -99,6 +99,13 @@ public virtual void Visit(OpenApiPaths paths)
         {
         }
 
+        /// <summary>
+        /// Visits Webhooks>
+        /// </summary>
+        public virtual void Visit(IDictionary<string, OpenApiPathItem> webhooks)
+        {
+        }
+
         /// <summary>
         /// Visits <see cref="OpenApiPathItem"/>
         /// </summary>

src/Microsoft.OpenApi/Services/OpenApiWalker.cs

@@ -46,6 +46,7 @@ public void Walk(OpenApiDocument doc)
             Walk(OpenApiConstants.Info, () => Walk(doc.Info));
             Walk(OpenApiConstants.Servers, () => Walk(doc.Servers));
             Walk(OpenApiConstants.Paths, () => Walk(doc.Paths));
+            Walk(OpenApiConstants.Webhooks, () => Walk(doc.Webhooks));
             Walk(OpenApiConstants.Components, () => Walk(doc.Components));
             Walk(OpenApiConstants.Security, () => Walk(doc.SecurityRequirements));
             Walk(OpenApiConstants.ExternalDocs, () => Walk(doc.ExternalDocs));
@@ -221,6 +222,28 @@ internal void Walk(OpenApiPaths paths)
             }
         }
 
+        /// <summary>
+        /// Visits Webhooks and child objects
+        /// </summary>
+        internal void Walk(IDictionary<string, OpenApiPathItem> webhooks)
+        {
+            if (webhooks == null)
+            {
+                return;
+            }
+
+            _visitor.Visit(webhooks);
+
+            // Visit Webhooks
+            if (webhooks != null)
+            {
+                foreach (var pathItem in webhooks)
+                {
+                    Walk(pathItem.Key, () => Walk(pathItem.Value));
+                }
+            }
+        }
+
         /// <summary>
         /// Visits list of  <see cref="OpenApiServer"/> and child objects
         /// </summary>

src/Microsoft.OpenApi/Validations/Rules/OpenApiDocumentRules.cs

@@ -28,15 +28,6 @@ public static class OpenApiDocumentRules
                             String.Format(SRResource.Validation_FieldIsRequired, "info", "document"));
                     }
                     context.Exit();
-
-                    // paths
-                    context.Enter("paths");
-                    if (item.Paths == null)
-                    {
-                        context.CreateError(nameof(OpenApiDocumentFieldIsMissing),
-                            String.Format(SRResource.Validation_FieldIsRequired, "paths", "document"));
-                    }
-                    context.Exit();
                 });
     }
 }

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

@@ -137,6 +137,9 @@
       <EmbeddedResource Include="V3Tests\Samples\OpenApiDocument\minimalDocument.yaml">
         <CopyToOutputDirectory>Never</CopyToOutputDirectory>
       </EmbeddedResource>
+      <EmbeddedResource Include="V3Tests\Samples\OpenApiDocument\documentWithWebhooks.yaml">
+        <CopyToOutputDirectory>Never</CopyToOutputDirectory>
+      </EmbeddedResource>
       <EmbeddedResource Include="V3Tests\Samples\OpenApiDocument\apiWithFullHeaderComponent.yaml">
         <CopyToOutputDirectory>Never</CopyToOutputDirectory>
       </EmbeddedResource>

test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiDocumentTests.cs

@@ -1327,5 +1327,218 @@ public void HeaderParameterShouldAllowExample()
                     });
             }
         }
+
+        [Fact]
+        public void ParseDocumentWithWebhooksShouldSucceed()
+        {
+            // Arrange and Act
+            using var stream = Resources.GetStream(Path.Combine(SampleFolderPath, "documentWithWebhooks.yaml"));
+            var actual = new OpenApiStreamReader().Read(stream, out var diagnostic);
+
+            var components = new OpenApiComponents
+            {
+                Schemas = new Dictionary<string, OpenApiSchema>
+                {
+                    ["pet"] = new OpenApiSchema
+                    {
+                        Type = "object",
+                        Required = new HashSet<string>
+                            {
+                                "id",
+                                "name"
+                            },
+                        Properties = new Dictionary<string, OpenApiSchema>
+                        {
+                            ["id"] = new OpenApiSchema
+                            {
+                                Type = "integer",
+                                Format = "int64"
+                            },
+                            ["name"] = new OpenApiSchema
+                            {
+                                Type = "string"
+                            },
+                            ["tag"] = new OpenApiSchema
+                            {
+                                Type = "string"
+                            },
+                        },
+                        Reference = new OpenApiReference
+                        {
+                            Type = ReferenceType.Schema,
+                            Id = "pet",
+                            HostDocument = actual
+                        }
+                    },
+                    ["newPet"] = new OpenApiSchema
+                    {
+                        Type = "object",
+                        Required = new HashSet<string>
+                            {
+                                "name"
+                            },
+                        Properties = new Dictionary<string, OpenApiSchema>
+                        {
+                            ["id"] = new OpenApiSchema
+                            {
+                                Type = "integer",
+                                Format = "int64"
+                            },
+                            ["name"] = new OpenApiSchema
+                            {
+                                Type = "string"
+                            },
+                            ["tag"] = new OpenApiSchema
+                            {
+                                Type = "string"
+                            },
+                        },
+                        Reference = new OpenApiReference
+                        {
+                            Type = ReferenceType.Schema,
+                            Id = "newPet",
+                            HostDocument = actual
+                        }
+                    }
+                }
+            };
+
+            // Create a clone of the schema to avoid modifying things in components.
+            var petSchema = Clone(components.Schemas["pet"]);
+
+            petSchema.Reference = new OpenApiReference
+            {
+                Id = "pet",
+                Type = ReferenceType.Schema,
+                HostDocument = actual
+            };
+
+            var newPetSchema = Clone(components.Schemas["newPet"]);
+
+            newPetSchema.Reference = new OpenApiReference
+            {
+                Id = "newPet",
+                Type = ReferenceType.Schema,
+                HostDocument = actual
+            };
+
+            var expected = new OpenApiDocument
+            {
+                Info = new OpenApiInfo
+                {
+                    Version = "1.0.0",
+                    Title = "Webhook Example"                    
+                },
+                Webhooks = new OpenApiPaths
+                {
+                    ["/pets"] = new OpenApiPathItem
+                    {
+                        Operations = new Dictionary<OperationType, OpenApiOperation>
+                        {
+                            [OperationType.Get] = new OpenApiOperation
+                            {
+                                Description = "Returns all pets from the system that the user has access to",
+                                OperationId = "findPets",
+                                Parameters = new List<OpenApiParameter>
+                                    {
+                                        new OpenApiParameter
+                                        {
+                                            Name = "tags",
+                                            In = ParameterLocation.Query,
+                                            Description = "tags to filter by",
+                                            Required = false,
+                                            Schema = new OpenApiSchema
+                                            {
+                                                Type = "array",
+                                                Items = new OpenApiSchema
+                                                {
+                                                    Type = "string"
+                                                }
+                                            }
+                                        },
+                                        new OpenApiParameter
+                                        {
+                                            Name = "limit",
+                                            In = ParameterLocation.Query,
+                                            Description = "maximum number of results to return",
+                                            Required = false,
+                                            Schema = new OpenApiSchema
+                                            {
+                                                Type = "integer",
+                                                Format = "int32"
+                                            }
+                                        }
+                                    },
+                                Responses = new OpenApiResponses
+                                {
+                                    ["200"] = new OpenApiResponse
+                                    {
+                                        Description = "pet response",
+                                        Content = new Dictionary<string, OpenApiMediaType>
+                                        {
+                                            ["application/json"] = new OpenApiMediaType
+                                            {
+                                                Schema = new OpenApiSchema
+                                                {
+                                                    Type = "array",
+                                                    Items = petSchema
+                                                }
+                                            },
+                                            ["application/xml"] = new OpenApiMediaType
+                                            {
+                                                Schema = new OpenApiSchema
+                                                {
+                                                    Type = "array",
+                                                    Items = petSchema
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            },
+                            [OperationType.Post] = new OpenApiOperation
+                            {
+                                RequestBody = new OpenApiRequestBody
+                                {
+                                    Description = "Information about a new pet in the system",
+                                    Required = true,
+                                    Content = new Dictionary<string, OpenApiMediaType>
+                                    {
+                                        ["application/json"] = new OpenApiMediaType
+                                        {
+                                            Schema = newPetSchema
+                                        }
+                                    }
+                                },
+                                Responses = new OpenApiResponses
+                                {
+                                    ["200"] = new OpenApiResponse
+                                    {
+                                        Description = "Return a 200 status to indicate that the data was received successfully",
+                                        Content = new Dictionary<string, OpenApiMediaType>
+                                        {
+                                            ["application/json"] = new OpenApiMediaType
+                                            {
+                                                Schema = petSchema
+                                            },
+                                        }
+                                    }
+                                }
+                            }
+                        },
+                        Reference = new OpenApiReference
+                        {
+                            Type = ReferenceType.PathItem,
+                            Id = "/pets"
+                        }
+                    }
+                },
+                Components = components
+            };
+
+            // Assert
+            diagnostic.Should().BeEquivalentTo(new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_0 });
+            actual.Should().BeEquivalentTo(expected);
+        }
     }
 }