Fixing .Net 10 support (#161)

* Fixing .Net 10 support

* Allowing consumers to overwrite the Swashbuckle.AspNetCore package as they please

* Fixing default version that was wrongfully changed

* Fixing failing tests by updating the OpenApi spec

* Updating readme

Author: MatDumoulin

README.md

@@ -19,6 +19,18 @@ For the TLDR version:
 - The default value are defined in the property group on the target `ValidateOpenApi` in this file `./src/Workleap.OpenApi.MSBuild/msbuild/tools/Workleap.OpenApi.MSBuild.targets`
 - Users can select whether to validate the API with frontend or backend ruleset depending on how they configure the `OpenApiServiceProfile` MSBuild property ([`backend` (default)](https://github.com/workleap/wl-api-guidelines/blob/main/.spectral.backend.yaml) or [`frontend`](https://github.com/workleap/wl-api-guidelines/blob/main/.spectral.frontend.yaml)).
 
+## Which Swashbuckle.AspNetCore.Cli version is used?
+The MSBuild task uses `Swashbuckle.AspNetCore.Cli` to generate OpenAPI specifications. The version is resolved in the following order (highest to lowest priority):
+
+1. **Explicit configuration** - Set via the `OpenApiSwaggerVersion` MSBuild property:
+```xml
+   <PropertyGroup>
+     <OpenApiSwaggerVersion>10.3.0</OpenApiSwaggerVersion>
+   </PropertyGroup>
+```
+2. Project dependency - If your project references Swashbuckle.AspNetCore (via *.csproj or Directory.Packages.props), the same version is used.
+3. Default version - Falls back to version 10.1.0 if no version is found.
+
 ## How to test locally
 
 ### How debug the project

src/WebApiDebugger/WebApiDebugger.csproj

@@ -5,14 +5,13 @@
     <ImplicitUsings>enable</ImplicitUsings>
     <IsPackable>false</IsPackable>
     <WarnOnPackingNonPackableProject>false</WarnOnPackingNonPackableProject>
-    <OpenApiEnabled>true</OpenApiEnabled>
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Swashbuckle.AspNetCore" Version="9.0.6" />
+    <PackageReference Include="Swashbuckle.AspNetCore" Version="10.1.0" />
   </ItemGroup>
   <PropertyGroup>
-    <OpenApiEnabled>false</OpenApiEnabled>
+    <OpenApiEnabled>true</OpenApiEnabled>
     <OpenApiDebuggingEnabled>true</OpenApiDebuggingEnabled>
     <OpenApiDevelopmentMode>GenerateContract</OpenApiDevelopmentMode>
   </PropertyGroup>

src/WebApiDebugger/openapi-v1.yaml

@@ -1,4 +1,5 @@
-openapi: 3.0.1
+# DO NOT EDIT. This is a generated file
+openapi: 3.0.4
 info:
   title: WebApiDebugger
   version: '1.0'
@@ -35,4 +36,6 @@ components:
         summary:
           type: string
           nullable: true
-      additionalProperties: false
+      additionalProperties: false
+tags:
+  - name: WeatherForecast

src/Workleap.OpenApi.MSBuild/SwaggerManager.cs

@@ -5,7 +5,6 @@ namespace Workleap.OpenApi.MSBuild;
 
 internal sealed class SwaggerManager : ISwaggerManager
 {
-    private const string SwaggerVersion = "9.0.4";
     private const string DoNotEditComment = "# DO NOT EDIT. This is a generated file\n";
     private const int MaxRetryCount = 3;
     private readonly IProcessWrapper _processWrapper;
@@ -14,14 +13,16 @@ internal sealed class SwaggerManager : ISwaggerManager
     private readonly string _swaggerDirectory;
     private readonly string _openApiToolsDirectoryPath;
     private readonly string _swaggerExecutablePath;
+    private readonly string _swaggerVersion;
 
-    public SwaggerManager(ILoggerWrapper loggerWrapper, IProcessWrapper processWrapper, string openApiToolsDirectoryPath, string openApiWebApiAssemblyPath)
+    public SwaggerManager(ILoggerWrapper loggerWrapper, IProcessWrapper processWrapper, string openApiToolsDirectoryPath, string openApiWebApiAssemblyPath, string swaggerVersion)
     {
         this._processWrapper = processWrapper;
         this._loggerWrapper = loggerWrapper;
         this._openApiWebApiAssemblyPath = openApiWebApiAssemblyPath;
         this._openApiToolsDirectoryPath = openApiToolsDirectoryPath;
-        this._swaggerDirectory = Path.Combine(openApiToolsDirectoryPath, "swagger", SwaggerVersion);
+        this._swaggerVersion = swaggerVersion;
+        this._swaggerDirectory = Path.Combine(openApiToolsDirectoryPath, "swagger", swaggerVersion);
         this._swaggerExecutablePath = Path.Combine(this._swaggerDirectory, RuntimeInformation.IsOSPlatform(OSPlatform.Windows) ? "swagger.exe" : "swagger");
     }
 
@@ -48,13 +49,13 @@ public async Task InstallSwaggerCliAsync(CancellationToken cancellationToken)
             return;
         }
 
-        this._loggerWrapper.LogMessage($"🔧 Installing Swashbuckle.AspNetCore.Cli {SwaggerVersion}...");
+        this._loggerWrapper.LogMessage($"🔧 Installing Swashbuckle.AspNetCore.Cli {this._swaggerVersion}...");
 
         for (var retryCount = 0; retryCount < MaxRetryCount; retryCount++)
         {
             var result = await this._processWrapper.RunProcessAsync(
                 "dotnet",
-                ["tool", "update", "Swashbuckle.AspNetCore.Cli", "--ignore-failed-sources", "--tool-path", this._swaggerDirectory, "--configfile", Path.Combine(this._openApiToolsDirectoryPath, "nuget.config"), "--version", SwaggerVersion],
+                ["tool", "update", "Swashbuckle.AspNetCore.Cli", "--ignore-failed-sources", "--tool-path", this._swaggerDirectory, "--configfile", Path.Combine(this._openApiToolsDirectoryPath, "nuget.config"), "--version", this._swaggerVersion],
                 cancellationToken);
 
             var isLastRetry = retryCount == MaxRetryCount - 1;
@@ -75,7 +76,7 @@ public async Task InstallSwaggerCliAsync(CancellationToken cancellationToken)
             break;
         }
 
-        this._loggerWrapper.LogMessage($"✅ Swashbuckle.AspNetCore.Cli {SwaggerVersion} installed successfully.");
+        this._loggerWrapper.LogMessage($"✅ Swashbuckle.AspNetCore.Cli {this._swaggerVersion} installed successfully.");
     }
 
     public async Task<string> GenerateOpenApiSpecAsync(string swaggerExePath, string outputOpenApiSpecPath, string documentName, CancellationToken cancellationToken)

src/Workleap.OpenApi.MSBuild/ValidateOpenApiTask.cs

@@ -58,6 +58,10 @@ public sealed class ValidateOpenApiTask : CancelableAsyncTask
     /// <summary>If warnings should be logged as errors instead.</summary>
     public bool OpenApiTreatWarningsAsErrors { get; set; }
 
+    /// <summary>The version of Swashbuckle.AspNetCore.Cli to use for generating OpenAPI specs.</summary>
+    [Required]
+    public string OpenApiSwaggerVersion { get; set; } = string.Empty;
+
     protected override async Task<bool> ExecuteAsync(CancellationToken cancellationToken)
     {
         var loggerWrapper = new LoggerWrapper(this.Log, this.OpenApiTreatWarningsAsErrors);
@@ -73,6 +77,7 @@ protected override async Task<bool> ExecuteAsync(CancellationToken cancellationT
         loggerWrapper.LogMessage("{0} = '{1}'", MessageImportance.Low, nameof(this.OpenApiSpectralRulesetUrl), this.OpenApiSpectralRulesetUrl ?? "No custom ruleset provided");
         loggerWrapper.LogMessage("{0} = '{1}'", MessageImportance.Low, nameof(this.OpenApiSwaggerDocumentNames), string.Join(", ", this.OpenApiSwaggerDocumentNames));
         loggerWrapper.LogMessage("{0} = '{1}'", MessageImportance.Low, nameof(this.OpenApiSpecificationFiles), string.Join(", ", this.OpenApiSpecificationFiles));
+        loggerWrapper.LogMessage("{0} = '{1}'", MessageImportance.Normal, nameof(this.OpenApiSwaggerVersion), this.OpenApiSwaggerVersion);
 
         if (this.OpenApiSpecificationFiles.Length != this.OpenApiSwaggerDocumentNames.Length)
         {
@@ -88,7 +93,7 @@ protected override async Task<bool> ExecuteAsync(CancellationToken cancellationT
 
         var reportsPath = Path.Combine(this.OpenApiToolsDirectoryPath, "reports");
         var processWrapper = new ProcessWrapper(this.StartupAssemblyPath);
-        var swaggerManager = new SwaggerManager(loggerWrapper, processWrapper, this.OpenApiToolsDirectoryPath, this.OpenApiWebApiAssemblyPath);
+        var swaggerManager = new SwaggerManager(loggerWrapper, processWrapper, this.OpenApiToolsDirectoryPath, this.OpenApiWebApiAssemblyPath, this.OpenApiSwaggerVersion);
         var diffCalculator = new DiffCalculator(Path.Combine(this.OpenApiToolsDirectoryPath, "spectral-state"));
 
         var httpClientWrapper = new HttpClientWrapper();

src/Workleap.OpenApi.MSBuild/msbuild/tools/Workleap.OpenApi.MSBuild.targets

@@ -55,6 +55,12 @@
       <!-- Use TreatWarningsAsErrors property unless it is opt-out with OpenApiTreatWarningsAsErrors, fallback to false if both are unset -->
       <OpenApiTreatWarningsAsErrors Condition="'$(OpenApiTreatWarningsAsErrors)' == ''">$(TreatWarningsAsErrors)</OpenApiTreatWarningsAsErrors>
       <OpenApiTreatWarningsAsErrors Condition="'$(OpenApiTreatWarningsAsErrors)' == ''">false</OpenApiTreatWarningsAsErrors>
+
+      <!-- The version of Swashbuckle.AspNetCore.Cli to use for generating OpenAPI specs -->
+      <!-- Fallback chain: explicit property -> PackageVersion (CPM) -> PackageReference -> default -->
+      <OpenApiSwaggerVersion Condition="'$(OpenApiSwaggerVersion)' == ''">@(PackageVersion->WithMetadataValue('Identity', 'Swashbuckle.AspNetCore')->Metadata('Version'))</OpenApiSwaggerVersion>
+      <OpenApiSwaggerVersion Condition="'$(OpenApiSwaggerVersion)' == ''">@(PackageReference->WithMetadataValue('Identity', 'Swashbuckle.AspNetCore')->Metadata('Version'))</OpenApiSwaggerVersion>
+      <OpenApiSwaggerVersion Condition="'$(OpenApiSwaggerVersion)' == ''">10.1.0</OpenApiSwaggerVersion>
     </PropertyGroup>
 
     <ItemGroup>
@@ -83,6 +89,7 @@
       OpenApiSpecificationFiles="$(OpenApiSpecificationFiles)"
       OpenApiTreatWarningsAsErrors="$(OpenApiTreatWarningsAsErrors)"
       OpenApiServiceProfile="$(OpenApiServiceProfile)"
+      OpenApiSwaggerVersion="$(OpenApiSwaggerVersion)"
     />
     <Touch Files="$(IntermediateOutputPath)$(OpenApiTouchFileName)" AlwaysCreate="true" />
   </Target>

src/tests/WebApi.MsBuild.SystemTest.GenericTest/Program.cs

@@ -1,4 +1,4 @@
-using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi;
 
 var builder = WebApplication.CreateBuilder(args);
 

src/tests/WebApi.MsBuild.SystemTest.GenericTest/WebApi.MsBuild.SystemTest.GenericTest.csproj

@@ -16,6 +16,6 @@
     </PropertyGroup>
 
     <ItemGroup>
-        <PackageReference Include="Swashbuckle.AspNetCore" Version="9.0.6" />
+        <PackageReference Include="Swashbuckle.AspNetCore" Version="10.1.0" />
     </ItemGroup>
 </Project>

src/tests/WebApi.MsBuild.SystemTest.GenericTest/openapi-v1-management.yaml

@@ -1,3 +1,4 @@
+# DO NOT EDIT. This is a generated file
 openapi: 3.0.4
 info:
   title: V1 API management
@@ -10,7 +11,7 @@ paths:
       operationId: GetWeatherSources
       responses:
         '200':
-          description: Success
+          description: OK
           content:
             application/json:
               schema:
@@ -53,4 +54,6 @@ components:
         source:
           type: string
           nullable: true
-      additionalProperties: false
+      additionalProperties: false
+tags:
+  - name: WeatherManagement

src/tests/WebApi.MsBuild.SystemTest.GenericTest/openapi-v1.yaml

@@ -1,3 +1,4 @@
+# DO NOT EDIT. This is a generated file
 openapi: 3.0.4
 info:
   title: V1 API General
@@ -10,7 +11,7 @@ paths:
       operationId: GetWeatherForecast
       responses:
         '200':
-          description: Success
+          description: OK
           content:
             application/json:
               schema:
@@ -61,4 +62,6 @@ components:
         summary:
           type: string
           nullable: true
-      additionalProperties: false
+      additionalProperties: false
+tags:
+  - name: WeatherForecast