[Repo Assist] eng: evaluate Microsoft.OpenApi 3.x migration

[github-actions]

🤖 This issue was created by Repo Assist, an automated AI assistant. Please adjust or close if this is not a priority.

Background

SwaggerProvider currently depends on Microsoft.OpenApi ~> 2 (pinned in paket.dependencies). The latest released version is 3.5.1, which is a major version bump with breaking API changes.

Why this matters

• The v2 series will eventually stop receiving updates
• OpenAPI 3.1 support (required for schemas using JSON Schema keywords like unevaluatedProperties, prefixItems, etc.) may require v3 of the reader
• v3 brings improved nullable/required handling that could help address issues like String field cannot be optional. #122 and Generator ignores nullability #178

Known breaking changes in Microsoft.OpenApi 3.x

From the OpenAPI.NET changelog:

• OpenApiSchema API changes (property renames, type changes)
• OpenApiDocument.Parse signature changes
• IOpenApiSchema refactoring

Suggested approach

1. Create a feature branch eng/openapi-3x-migration
2. Bump microsoft.openapi constraint to ~> 3 in paket.dependencies
3. Fix compilation errors in DefinitionCompiler.fs and OperationCompiler.fs
4. Run the full test suite (unit + provider integration tests)
5. Update Provider.OpenApiClient.fs to use any new APIs that simplify the nullable/required handling

This is non-trivial work but would future-proof the library. A major version bump of SwaggerProvider would be appropriate to signal the upstream change.

Current state

• Current: Microsoft.OpenApi 2.7.2
• Latest: Microsoft.OpenApi 3.5.1
• Risk: high — breaking API changes require careful migration

Generated by 🌈 Repo Assist, see workflow run. Learn more.

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@7ee2b60744abf71b985bead4599640f165edcd93

[sergey-tihon]

Microsoft.OpenApi 3.x is no longer supported by AspNetCore OpenAPI. We probably should wait at least till .NET 11

Microsoft.OpenApi 3.x