[Repo Assist] fix: helpful error when Swagger 2.0 schema used with OpenApiClientProvider

[github-actions]

🤖 This PR was created by Repo Assist, an automated AI assistant.

Summary

When a user accidentally uses a Swagger 2.0 (OpenAPI v2) schema URL with OpenApiClientProvider, the error message was confusing (a generic parse error or an IDE-level "error parsing doc comment" tooltip). This PR adds an explicit, actionable check.

Closes #231

Root Cause

Microsoft.OpenApi can parse both v2 and v3 schemas. After parsing, OpenApiDiagnostic.SpecificationVersion is set to OpenApiSpecVersion.OpenApi2_0 when the schema is Swagger 2.0. Previously, there was no check on this value, so the provider would either produce a confusing parse error or generate an empty/broken type.

Fix

Added a guard immediately after schema parsing in Provider.OpenApiClient.fs:

if diagnostic.SpecificationVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi2_0 then
    failwithf
        "The schema '%s' is a Swagger 2.0 (OpenAPI v2) specification. \
OpenApiClientProvider supports OpenAPI v3 schemas only. \
For Swagger 2.0 schemas, use SwaggerClientProvider instead:\n    \
type Api = SwaggerClientProvider<\"%s\">"
        schemaPathRaw
        schemaPathRaw

The new error message is clear and tells users exactly what to do.

Trade-offs

• Breaking: Users who relied on OpenApiClientProvider with v2 schemas (even if it accidentally worked in some cases) will now get a compile-time error. However, those cases were never supported and the behaviour was undefined.
• No new dependencies: uses OpenApiSpecVersion which is already part of the Microsoft.OpenApi package.

Test Status

• ✅ Build succeeded: dotnet build SwaggerProvider.sln -c Release — 0 errors, 207 warnings (pre-existing)
• ✅ All 241 unit tests pass: dotnet tests/SwaggerProvider.Tests/bin/Release/net10.0/SwaggerProvider.Tests.dll
• ✅ Code formatting verified: dotnet fantomas --check passes

Generated by 🌈 Repo Assist at {run-started}. Learn more.

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@1f672aef974f4246124860fc532f82fe8a93a57e

[sergey-tihon]

we plan to drop swaggerprovider and OpenApiClientProvider will be the only one supported, so we don't want to break usage of V2 schemas is they work with OpenApiClientProvider