Add reusable path items to components object

src/Microsoft.OpenApi.Readers/OpenApiVersionExtensionMethods.cs

@@ -0,0 +1,61 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license.
+
+using System;
+
+namespace Microsoft.OpenApi.Readers
+{
+    /// <summary>
+    /// Generates custom extension methods for the version string type
+    /// </summary>
+    public static class OpenApiVersionExtensionMethods
+    {
+        /// <summary>
+        /// Extension method for Spec version 2.0
+        /// </summary>
+        /// <param name="version"></param>
+        /// <returns></returns>
+        public static bool is2_0(this string version)
+        {
+            bool result = false;
+            if (version.Equals("2.0", StringComparison.OrdinalIgnoreCase))
+            {
+                result = true;
+            }
+
+            return result;
+        }
+
+        /// <summary>
+        /// Extension method for Spec version 3.0
+        /// </summary>
+        /// <param name="version"></param>
+        /// <returns></returns>
+        public static bool is3_0(this string version)
+        {
+            bool result = false;
+            if (version.StartsWith("3.0", StringComparison.OrdinalIgnoreCase))
+            {
+                result = true;
+            }
+
+            return result;
+        }
+
+        /// <summary>
+        /// Extension method for Spec version 3.1
+        /// </summary>
+        /// <param name="version"></param>
+        /// <returns></returns>
+        public static bool is3_1(this string version)
+        {
+            bool result = false;
+            if (version.StartsWith("3.1", StringComparison.OrdinalIgnoreCase))
+            {
+                result = true;
+            }
+
+            return result;
+        }
+    }
+}

src/Microsoft.OpenApi.Readers/ParsingContext.cs

@@ -59,16 +59,18 @@ internal OpenApiDocument Parse(YamlDocument yamlDocument)
 
             switch (inputVersion)
             {
-                case string version when version == "2.0":
+                case string version when version.is2_0():
                     VersionService = new OpenApiV2VersionService(Diagnostic);
                     doc = VersionService.LoadDocument(RootNode);
                     this.Diagnostic.SpecificationVersion = OpenApiSpecVersion.OpenApi2_0;
+                    ValidateRequiredFields(doc, version);
                     break;
 
-                case string version when version.StartsWith("3.0"):
+                case string version when version.is3_0() || version.is3_1():
                     VersionService = new OpenApiV3VersionService(Diagnostic);
                     doc = VersionService.LoadDocument(RootNode);
                     this.Diagnostic.SpecificationVersion = OpenApiSpecVersion.OpenApi3_0;
+                    ValidateRequiredFields(doc, version);
                     break;
 
                 default:
@@ -244,5 +246,18 @@ public void PopLoop(string loopid)
             }
         }
 
+        private void ValidateRequiredFields(OpenApiDocument doc, string version)
+        {
+            if ((version.is2_0() || version.is3_0()) && (doc.Paths == null || !doc.Paths.Any()))
+            {
+                // paths is a required field in OpenAPI 3.0 but optional in 3.1
+                RootNode.Context.Diagnostic.Errors.Add(new OpenApiError("", $"Paths is a REQUIRED field at {RootNode.Context.GetLocation()}"));
+            }
+            else if (version.is3_1() && (doc.Paths == null || !doc.Paths.Any()) && (doc.Webhooks == null || !doc.Webhooks.Any()))
+            {
+                RootNode.Context.Diagnostic.Errors.Add(new OpenApiError(
+                    "", $"The document MUST contain either a Paths or Webhooks field at {RootNode.Context.GetLocation()}"));
+            }
+        }
     }
 }

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

@@ -17,9 +17,7 @@ internal static partial class OpenApiV3Deserializer
     {
         private static FixedFieldMap<OpenApiComponents> _componentsFixedFields = new FixedFieldMap<OpenApiComponents>
         {
-            {
-                "schemas", (o, n) => o.Schemas = n.CreateMapWithReference(ReferenceType.Schema, LoadSchema)
-            },
+            {"schemas", (o, n) => o.Schemas = n.CreateMapWithReference(ReferenceType.Schema, LoadSchema)},
             {"responses", (o, n) => o.Responses = n.CreateMapWithReference(ReferenceType.Response, LoadResponse)},
             {"parameters", (o, n) => o.Parameters = n.CreateMapWithReference(ReferenceType.Parameter, LoadParameter)},
             {"examples", (o, n) => o.Examples = n.CreateMapWithReference(ReferenceType.Example, LoadExample)},
@@ -28,9 +26,9 @@ internal static partial class OpenApiV3Deserializer
             {"securitySchemes", (o, n) => o.SecuritySchemes = n.CreateMapWithReference(ReferenceType.SecurityScheme, LoadSecurityScheme)},
             {"links", (o, n) => o.Links = n.CreateMapWithReference(ReferenceType.Link, LoadLink)},
             {"callbacks", (o, n) => o.Callbacks = n.CreateMapWithReference(ReferenceType.Callback, LoadCallback)},
+            {"pathItems", (o, n) => o.PathItems = n.CreateMapWithReference(ReferenceType.PathItem, LoadPathItem)}
         };
 
-
         private static PatternFieldMap<OpenApiComponents> _componentsPatternFields =
             new PatternFieldMap<OpenApiComponents>
             {

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 = LoadPaths(n)},
             {"components", (o, n) => o.Components = LoadComponents(n)},
             {"tags", (o, n) => {o.Tags = n.CreateList(LoadTag);
                 foreach (var tag in o.Tags)
@@ -50,7 +48,6 @@ internal static partial class OpenApiV3Deserializer
         public static OpenApiDocument LoadOpenApi(RootNode rootNode)
         {
             var openApidoc = new OpenApiDocument();
-
             var openApiNode = rootNode.GetMap();
 
             ParseMap(openApiNode, openApidoc, _openApiFixedFields, _openApiPatternFields);

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

@@ -56,6 +56,17 @@ public static OpenApiPathItem LoadPathItem(ParseNode node)
         {
             var mapNode = node.CheckMapNode("PathItem");
 
+            var pointer = mapNode.GetReferencePointer();
+
+            if (pointer != null)
+            {
+                return new OpenApiPathItem()
+                {
+                    UnresolvedReference = true,
+                    Reference = node.Context.VersionService.ConvertToOpenApiReference(pointer, ReferenceType.PathItem)
+                };
+            }
+
             var pathItem = new OpenApiPathItem();
 
             ParseMap(mapNode, pathItem, _pathItemFixedFields, _pathItemPatternFields);

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

@@ -165,7 +165,12 @@ private OpenApiReference ParseLocalReference(string localReference)
                 if (segments[1] == "components")
                 {
                     var referenceType = segments[2].GetEnumFromDisplayName<ReferenceType>();
-                    return new OpenApiReference { Type = referenceType, Id = segments[3] };
+                    var refId = segments[3];
+                    if (segments[2] == "pathItems")
+                    {
+                        refId = "/" + segments[3];
+                    };
+                    return new OpenApiReference { Type = referenceType, Id = refId };
                 }
             }
 

src/Microsoft.OpenApi/Models/OpenApiComponents.cs

@@ -1,10 +1,8 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license. 
 
-using System;
 using System.Collections.Generic;
 using System.Linq;
-using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Writers;
 
@@ -63,6 +61,11 @@ public class OpenApiComponents : IOpenApiSerializable, IOpenApiExtensible
         /// </summary>
         public IDictionary<string, OpenApiCallback> Callbacks { get; set; } = new Dictionary<string, OpenApiCallback>();
 
+        /// <summary>
+        /// An object to hold reusable <see cref="OpenApiPathItem"/> Object.
+        /// </summary>
+        public IDictionary<string, OpenApiPathItem> PathItems { get; set; } = new Dictionary<string, OpenApiPathItem>();
+
         /// <summary>
         /// This object MAY be extended with Specification Extensions.
         /// </summary>
@@ -87,6 +90,7 @@ public OpenApiComponents(OpenApiComponents components)
             SecuritySchemes = components?.SecuritySchemes != null ? new Dictionary<string, OpenApiSecurityScheme>(components.SecuritySchemes) : null;
             Links = components?.Links != null ? new Dictionary<string, OpenApiLink>(components.Links) : null;
             Callbacks = components?.Callbacks != null ? new Dictionary<string, OpenApiCallback>(components.Callbacks) : null;
+            PathItems = components?.PathItems != null ? new Dictionary<string, OpenApiPathItem>(components.PathItems) : null;
             Extensions = components?.Extensions != null ? new Dictionary<string, IOpenApiExtension>(components.Extensions) : null;
         }
 
@@ -288,7 +292,25 @@ public void SerializeAsV3(IOpenApiWriter writer)
                         component.SerializeAsV3(w);
                     }
                 });
-
+
+            // pathItems
+            writer.WriteOptionalMap(
+                OpenApiConstants.PathItems,
+                PathItems,
+                (w, key, component) =>
+                {
+                    if (component.Reference != null &&
+                        component.Reference.Type == ReferenceType.Schema &&
+                        component.Reference.Id == key)
+                    {
+                        component.SerializeAsV3WithoutReference(w);
+                    }
+                    else
+                    {
+                        component.SerializeAsV3(w);
+                    }
+                });
+
             // extensions
             writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi3_0);
 

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>
@@ -75,6 +80,11 @@ public static class OpenApiConstants
         /// </summary>
         public const string Components = "components";
 
+        /// <summary>
+        /// Field: PathItems
+        /// </summary>
+        public const string PathItems = "pathItems";
+
         /// <summary>
         /// Field: Security
         /// </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.PathItem &&
+                        component.Reference.Id == key)
+                    {
+                        component.SerializeAsV3WithoutReference(w);
+                    }
+                    else
+                    {
+                        component.SerializeAsV3(w);
+                    }
+                });
+
             // components
             writer.WriteOptionalObject(OpenApiConstants.Components, Components, (w, c) => c.SerializeAsV3(w));
 
@@ -479,7 +505,10 @@ internal IOpenApiReferenceable ResolveReference(OpenApiReference reference, bool
                 {
                     case ReferenceType.Schema:
                         return this.Components.Schemas[reference.Id];
-
+
+                    case ReferenceType.PathItem:
+                        return this.Components.PathItems[reference.Id];
+
                     case ReferenceType.Response:
                         return this.Components.Responses[reference.Id];
 

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("pathItems")] PathItem
     }
 }

src/Microsoft.OpenApi/Services/OpenApiReferenceResolver.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license. 
 
 using System;
@@ -70,6 +70,7 @@ public override void Visit(OpenApiComponents components)
             ResolveMap(components.Callbacks);
             ResolveMap(components.Examples);
             ResolveMap(components.Schemas);
+            ResolveMap(components.PathItems);
             ResolveMap(components.SecuritySchemes);
             ResolveMap(components.Headers);
         }
@@ -83,6 +84,15 @@ public override void Visit(IDictionary<string, OpenApiCallback> callbacks)
             ResolveMap(callbacks);
         }
 
+        /// <summary>
+        /// Resolves all references used in webhooks
+        /// </summary>
+        /// <param name="webhooks"></param>
+        public override void Visit(IDictionary<string, OpenApiPathItem> webhooks)
+        {
+            ResolveMap(webhooks);
+        }
+
         /// <summary>
         /// Resolve all references used in an operation
         /// </summary>
@@ -301,7 +311,7 @@ private void ResolveTags(IList<OpenApiTag> tags)
 
         private bool IsUnresolvedReference(IOpenApiReferenceable possibleReference)
         {
-            return (possibleReference != null && possibleReference.UnresolvedReference);
+            return possibleReference != null && possibleReference.UnresolvedReference;
         }
     }
 }

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>