feat(document): add GetOperationById to search operations across path… (#3025)

* feat(document): add GetOperationById to search operations across paths and webhooks

* refactor(document): replace Concat with dedicated GetAllOperations iterator

* refactor(document): extract GetOperationsFromPathItems to eliminate duplicate iteration

* refactor(document): simplify GetOperationById using single-pass helper

Signed-off-by: Vincent Biret <vibiret@microsoft.com>

Author: Mahdigln

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

@@ -815,6 +815,34 @@ static bool AddToDictionary<TValue>(IDictionary<string, TValue> dict, string key
             // Register only if it was actually added to the collection
             return added && (Workspace?.RegisterComponentForDocument(this, componentToRegister, id) ?? false);
         }
+
+        /// <summary>
+        /// Finds an operation in the document by its operation ID.
+        /// </summary>
+        /// <param name="operationId">The operation ID to search for.</param>
+        /// <returns>The matching <see cref="OpenApiOperation"/>, or <see langword="null"/> if not found.</returns>
+        public OpenApiOperation? GetOperationById(string operationId)
+        {
+            Utils.CheckArgumentNullOrEmpty(operationId);
+
+            return GetOperationByIdFromPathItems(Paths, operationId) ??
+                (Webhooks is not null ?
+                    GetOperationByIdFromPathItems(Webhooks, operationId) : null);
+        }
+
+        private static OpenApiOperation? GetOperationByIdFromPathItems(IDictionary<string, IOpenApiPathItem> pathItems, string operationId)
+        {
+            foreach (var pathItem in pathItems.Values)
+            {
+                if (pathItem.Operations is null) continue;
+                foreach (var operation in pathItem.Operations.Values)
+                {
+                    if (string.Equals(operation.OperationId, operationId, StringComparison.Ordinal))
+                        return operation;
+                }
+            }
+            return null;
+        }
     }
 
     internal class FindSchemaReferences : OpenApiVisitorBase

src/Microsoft.OpenApi/PublicAPI.Unshipped.txt

@@ -1 +1,2 @@
 #nullable enable
+Microsoft.OpenApi.OpenApiDocument.GetOperationById(string! operationId) -> Microsoft.OpenApi.OpenApiOperation?

test/Microsoft.OpenApi.Tests/Models/OpenApiDocumentTests.cs

@@ -2419,5 +2419,198 @@ public async Task SerializeDocumentWithSecurityRequirementAsJsonWorks(OpenApiSpe
             Assert.NotNull(actualSecurity);
             Assert.True(JsonNode.DeepEquals(JsonNode.Parse(expected), actualSecurity));
         }
+
+        [Fact]
+        public void GetOperationById_ReturnsMatchingOperation()
+        {
+            var operation = new OpenApiOperation { OperationId = "getUser" };
+            var doc = new OpenApiDocument
+            {
+                Info = new OpenApiInfo { Title = "Test", Version = "1.0" },
+                Paths = new OpenApiPaths
+                {
+                    ["/users/{id}"] = new OpenApiPathItem
+                    {
+                        Operations = new Dictionary<HttpMethod, OpenApiOperation>
+                        {
+                            [HttpMethod.Get] = operation
+                        }
+                    }
+                }
+            };
+
+            var result = doc.GetOperationById("getUser");
+
+            Assert.Same(operation, result);
+        }
+
+        [Fact]
+        public void GetOperationById_ReturnsNullWhenNotFound()
+        {
+            var doc = new OpenApiDocument
+            {
+                Info = new OpenApiInfo { Title = "Test", Version = "1.0" },
+                Paths = new OpenApiPaths
+                {
+                    ["/users"] = new OpenApiPathItem
+                    {
+                        Operations = new Dictionary<HttpMethod, OpenApiOperation>
+                        {
+                            [HttpMethod.Get] = new OpenApiOperation { OperationId = "listUsers" }
+                        }
+                    }
+                }
+            };
+
+            var result = doc.GetOperationById("nonExistentId");
+
+            Assert.Null(result);
+        }
+
+        [Fact]
+        public void GetOperationById_SearchesWebhooks()
+        {
+            var webhookOperation = new OpenApiOperation { OperationId = "onUserCreated" };
+            var doc = new OpenApiDocument
+            {
+                Info = new OpenApiInfo { Title = "Test", Version = "1.0" },
+                Paths = [],
+                Webhooks = new Dictionary<string, IOpenApiPathItem>
+                {
+                    ["userCreated"] = new OpenApiPathItem
+                    {
+                        Operations = new Dictionary<HttpMethod, OpenApiOperation>
+                        {
+                            [HttpMethod.Post] = webhookOperation
+                        }
+                    }
+                }
+            };
+
+            var result = doc.GetOperationById("onUserCreated");
+
+            Assert.Same(webhookOperation, result);
+        }
+
+        [Fact]
+        public void GetOperationById_IsCaseSensitive()
+        {
+            var doc = new OpenApiDocument
+            {
+                Info = new OpenApiInfo { Title = "Test", Version = "1.0" },
+                Paths = new OpenApiPaths
+                {
+                    ["/users"] = new OpenApiPathItem
+                    {
+                        Operations = new Dictionary<HttpMethod, OpenApiOperation>
+                        {
+                            [HttpMethod.Get] = new OpenApiOperation { OperationId = "getUser" }
+                        }
+                    }
+                }
+            };
+
+            Assert.NotNull(doc.GetOperationById("getUser"));
+            Assert.Null(doc.GetOperationById("GetUser"));
+            Assert.Null(doc.GetOperationById("GETUSER"));
+        }
+
+        [Fact]
+        public void GetOperationById_ResolvesOperationThroughPathItemReference()
+        {
+            const string yaml = """
+                openapi: '3.1.0'
+                info:
+                  title: Test
+                  version: 1.0.0
+                paths:
+                  /users:
+                    $ref: '#/components/pathItems/userPathItem'
+                components:
+                  pathItems:
+                    userPathItem:
+                      get:
+                        operationId: listUsers
+                        responses:
+                          '200':
+                            description: OK
+                """;
+
+            var doc = OpenApiDocument.Parse(yaml, OpenApiConstants.Yaml, SettingsFixture.ReaderSettings).Document;
+            doc.Workspace.RegisterComponents(doc);
+
+            var result = doc.GetOperationById("listUsers");
+
+            Assert.NotNull(result);
+            Assert.Equal("listUsers", result.OperationId);
+        }
+
+        [Fact]
+        public void GetOperationById_DuplicateIdReturnsFirstMatch()
+        {
+            // operationId must be unique per spec, but if not, Paths takes priority over Webhooks
+            var pathsOperation = new OpenApiOperation { OperationId = "duplicateId" };
+            var webhooksOperation = new OpenApiOperation { OperationId = "duplicateId" };
+            var doc = new OpenApiDocument
+            {
+                Info = new OpenApiInfo { Title = "Test", Version = "1.0" },
+                Paths = new OpenApiPaths
+                {
+                    ["/users"] = new OpenApiPathItem
+                    {
+                        Operations = new Dictionary<HttpMethod, OpenApiOperation>
+                        {
+                            [HttpMethod.Get] = pathsOperation
+                        }
+                    }
+                },
+                Webhooks = new Dictionary<string, IOpenApiPathItem>
+                {
+                    ["userEvent"] = new OpenApiPathItem
+                    {
+                        Operations = new Dictionary<HttpMethod, OpenApiOperation>
+                        {
+                            [HttpMethod.Post] = webhooksOperation
+                        }
+                    }
+                }
+            };
+
+            var result = doc.GetOperationById("duplicateId");
+
+            Assert.Same(pathsOperation, result);
+        }
+
+        [Fact]
+        public void GetOperationById_UnresolvedPathItemReferenceIsSkipped()
+        {
+            // An unresolved $ref has Target = null, so Operations = null — should be skipped gracefully
+            var unresolvedRef = new OpenApiPathItemReference("nonExistentPathItem", null);
+            var doc = new OpenApiDocument
+            {
+                Info = new OpenApiInfo { Title = "Test", Version = "1.0" },
+                Paths = new OpenApiPaths
+                {
+                    ["/users"] = unresolvedRef
+                }
+            };
+
+            var result = doc.GetOperationById("anyId");
+
+            Assert.Null(result);
+        }
+
+        [Fact]
+        public void GetOperationById_ThrowsOnNullOrEmptyId()
+        {
+            var doc = new OpenApiDocument
+            {
+                Info = new OpenApiInfo { Title = "Test", Version = "1.0" },
+                Paths = []
+            };
+
+            Assert.Throws<ArgumentNullException>(() => doc.GetOperationById(null!));
+            Assert.Throws<ArgumentNullException>(() => doc.GetOperationById(string.Empty));
+        }
     }
 }