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

[Mahdigln]

Description

Adds a GetOperationById(string operationId) method to OpenApiDocument that searches for an operation by its operationId across both Paths and Webhooks.

Closes #1654

Type of Change

• New feature (non-breaking change which adds functionality)

Related Issue(s)

Closes #1654

Changes Made

• Added GetOperationById(string operationId) method to OpenApiDocument
• Method searches both Paths and Webhooks to cover the full document
• Resolves operations through OpenApiPathItemReference (when the reference is resolved)
• Added GetOperationById entry to PublicAPI.Unshipped.txt

Testing

• Unit tests added/updated
• All existing tests pass

Tests cover:

• Returns matching operation from Paths
• Returns matching operation from Webhooks
• Returns null when not found
• Case-sensitive matching (getUser ≠ GetUser)
• Resolves operation through a $ref path item
• Returns first match when duplicate operationId exists (spec violation)
• Skips unresolved path item references gracefully
• Throws ArgumentNullException for null or empty operationId

Checklist

• My code follows the code style of this project
• I have performed a self-review of my own code
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Versions applicability

• I have evaluated the applicability of my change against the other versions above.

Additional Notes

GetOperationByRef (resolving operationRef via JSON Pointer) is not included in this PR and can be addressed in a follow-up.

[Vincent Biret (baywet)]

Thanks for the contribution!

[Vincent Biret (baywet)]

this is running at o(n) (n being the number of operations) and going to be really slow for larger API descriptions. Could you look into optimizing the search please?

[Mahdigln]

Thanks for the feedback! To address the O(n) concern, I'm thinking of building a lazy-initialized Dictionary<string, OpenApiOperation> index on the first call to GetOperationById, making subsequent lookups O(1). The trade-off is that the cache becomes stale if Paths or Webhooks are mutated after the index is built — but since OpenApiDocument is typically read-only after parsing, this seems acceptable.

Does this approach work for you, or do you have a different optimization in mind?

[Vincent Biret (baywet)]

That should work, but before we read into that index, we should be able to correlate whether the sources have changed since the last time we built the index and rebuild it if required.

[Mahdigln]

Thanks for the clarification! To implement change detection, I need to understand how to track mutations to Paths and Webhooks. A few options I'm considering:

Count-based: Compare Paths.Count and Webhooks?.Count — simple but misses replacements (same count, different items)
Version counter: Increment a counter whenever Paths or Webhooks is mutated — but OpenApiPaths doesn't expose change notifications today
Wrap collections: Replace OpenApiPaths with an observable/versioned collection that notifies the document on change

Do you have a preferred approach, or is there existing infrastructure in the codebase I should leverage?

[Vincent Biret (baywet)]

have you considered storing the hash code for those values next to the index. And ahead of querying the index, if the current hash codes don't match, recompute + update the values. ??

[Mahdigln]

Before implementing, one question: how should the hash be computed for Paths and Webhooks? Should I use the existing GetHashCodeAsync on the document, or compute something lighter like combining Paths.Count, Webhooks?.Count, and the hash codes of the keys?