Fix Swashbuckle CLI version mismatch for v10.x compatibility

[Copilot]

Swashbuckle.AspNetCore v10.0+ upgraded from Microsoft.OpenApi v1.x to v2.3.0, introducing breaking API changes. The hardcoded CLI version (9.0.4) caused TypeLoadException when generating specs for projects using v10.x, as the v9 CLI expected v1.x types but encountered v2.x types.

Changes

• Dynamic version detection: Detect Swashbuckle version from Swashbuckle.AspNetCore.SwaggerGen.dll in the application's output directory using FileVersionInfo
• Validation: Regex pattern ensures extracted version matches semantic versioning (e.g., 9.0.6, 10.0.1)
• Fallback: Defaults to 9.0.4 if detection fails (invalid path, missing DLL, or malformed version)
• No configuration required: Works automatically for both v9.x and v10.x projects

Implementation

// Constructor now detects version dynamically
var assemblyDirectory = Path.GetDirectoryName(openApiWebApiAssemblyPath);
this._swaggerVersion = this.DetectSwashbuckleVersion(assemblyDirectory) ?? DefaultSwaggerVersion;

private string? DetectSwashbuckleVersion(string? assemblyDirectory)
{
    // Find Swashbuckle.AspNetCore.SwaggerGen.dll
    var swashbuckleAssemblyPath = Path.Combine(assemblyDirectory, "Swashbuckle.AspNetCore.SwaggerGen.dll");
    
    // Extract and validate version using FileVersionInfo
    var versionInfo = FileVersionInfo.GetVersionInfo(swashbuckleAssemblyPath);
    var versionString = versionInfo.ProductVersion?.Split('+', '-')[0];
    
    // Validate semantic versioning pattern (major.minor.patch)
    if (Regex.IsMatch(versionString, @"^\d{1,4}\.\d{1,4}\.\d{1,4}(\.\d{1,4})?$"))
        return versionString;
    
    return null; // Falls back to default
}

The CLI tool version now matches the application's Swashbuckle version, preventing type loading conflicts across major version boundaries.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Incompatibility with Swashbuckle.AspNetCore v10.x due to hardcoded CLI version 9.0.4</issue_title>
<issue_description>Describe the bug

After upgrading Swashbuckle.AspNetCore from version 9.0.6 to 10.0.1 (which includes Microsoft.OpenApi v2.3.0), the Workleap.OpenApi.MSBuild package (v0.12.3) fails to generate OpenAPI specifications during the build process.

The build completes successfully for the main projects, but the OpenAPI spec generation step fails with a TypeLoadException when trying to load Microsoft.OpenApi.Models.OpenApiDocument from the Microsoft.OpenApi assembly.

To Reproduce

Steps to reproduce the behavior:

1. Update Swashbuckle.AspNetCore package reference from version 9.0.6 to 10.0.1 in a project that uses Workleap.OpenApi.MSBuild (v0.12.3)
2. Run dotnet build on the solution
3. Observe the OpenAPI spec generation failure in the build output

Expected behavior

The OpenAPI specification should be generated successfully during the build process, as it did with Swashbuckle.AspNetCore v9.0.6.

Error Output

Workleap.OpenApi.MSBuild.targets(75,5): Warning  : Unhandled exception. System.TypeLoadException: Could not load type 'Microsoft.OpenApi.Models.OpenApiDocument' from assembly 'Microsoft.OpenApi, Version=2.3.0.0, Culture=neutral, PublicKeyToken=3f5743946376f042'.
   at Swashbuckle.AspNetCore.Cli.Program.<>c.<Main>b__1_5(IDictionary`2 namedArgs)
   at Swashbuckle.AspNetCore.Cli.Program.<>c.<Main>b__1_5(IDictionary`2 namedArgs)
   at Swashbuckle.AspNetCore.Cli.CommandRunner.Run(IEnumerable`1 args) in /_/src/Swashbuckle.AspNetCore.Cli/CommandRunner.cs:line 56
   at Swashbuckle.AspNetCore.Cli.CommandRunner.Run(IEnumerable`1 args) in /_/src/Swashbuckle.AspNetCore.Cli/CommandRunner.cs:line 47
   at Swashbuckle.AspNetCore.Cli.Program.Main(String[] args) in /_/src/Swashbuckle.AspNetCore.Cli/Program.cs:line 199

Workleap.OpenApi.MSBuild.targets(75,5): Warning  : OpenAPI spec generation failed for C:\Sources\workleap-ai-connectors\connectors\api\src\Workleap.Ai.Connectors.WebApi\bin\Debug\net10.0\openapi\openapi-v1.yaml. Retrying again...

Workleap.OpenApi.MSBuild.targets(75,5): Warning  : An error occurred while validating the OpenAPI specification: OpenApi file for C:\Sources\workleap-ai-connectors\connectors\api\src\Workleap.Ai.Connectors.WebApi\bin\Debug\net10.0\openapi\openapi-v1.yaml could not be generated.

Environment (please complete the following information):

• OS: Windows 11
• .NET SDK: 10.0.100
• Target Framework: net10.0
• Swashbuckle.AspNetCore: 10.0.1 (upgraded from 9.0.6)
• Microsoft.OpenApi: 2.3.0 (transitive dependency from Swashbuckle v10)
• Workleap.OpenApi.MSBuild: 0.12.3
• IDE: Visual Studio / Rider

Additional context

The root cause is that Swashbuckle.AspNetCore v10.0.1 upgraded its dependency on Microsoft.OpenApi from v1.x to v2.3.0, which introduced breaking changes in the API. The Microsoft.OpenApi.Models namespace and types like OpenApiDocument have been restructured in v2.x.

The Workleap.OpenApi.MSBuild package (v0.12.3) uses Swashbuckle.AspNetCore.Cli internally to generate OpenAPI specs, but this CLI tool is not compatible with the new Microsoft.OpenApi v2.x API surface.

The issue is in the SwaggerManager.cs file where the Swashbuckle CLI version is hardcoded:

private const string SwaggerVersion = "9.0.4";

Source: SwaggerManager.cs:L7

This hardcoded version installs Swashbuckle.AspNetCore.Cli v9.0.4, which depends on Microsoft.OpenApi v1.x. When the consuming application uses Swashbuckle.AspNetCore v10.x (with Microsoft.OpenApi v2.x), there's a version mismatch between:

1. The CLI tool (v9.0.4) expecting Microsoft.OpenApi v1.x types
2. The application assembly (built with v10.x) containing Microsoft.OpenApi v2.x types

This causes the TypeLoadException when the CLI tool tries to load types from the incompatible Microsoft.OpenApi v2.x assembly.

Related Links:

• Swashbuckle.AspNetCore v10.0.0 Release Notes
• Microsoft.OpenApi v2.0.0 Breaking Changes
• Workleap.OpenApi.MSBuild SwaggerManager.cs

</issue_description>

Comments on the Issue (you are Copilot in this section)

Mathieu Dumoulin (@MatDumoulin) +1

We faced the same issue while trying to migrate SG Protect to .Net 10</comment_new>

• Fixes Incompatibility with Swashbuckle.AspNetCore v10.x due to hardcoded CLI version 9.0.4 #158

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.