Upgrade to .NET 10 and enhance OpenAPI support

marcominerva · marcominerva · commit a2e7cc0880ec · 2025-11-12T14:51:48.000+01:00
Updated projects to target .NET 10, leveraging new features and APIs.
Upgraded dependencies, including `Microsoft.AspNetCore.OpenApi`
and `Swashbuckle.AspNetCore.SwaggerUI`, to their latest versions.
Introduced conditional compilation for `net10.0` to support new
framework-specific features.

Enhanced OpenAPI integration:
- Added `DefaultResponseDocumentTransformer` for error schemas.
- Added `OAuth2AuthenticationDocumentTransformer` for OAuth2 support.
- Improved `AuthenticationDocumentTransformer` and
  `AuthenticationOperationTransformer` for security schemes and
  authorization policies.

Removed outdated `#if NET9_0_OR_GREATER` directives and replaced
them with more specific conditions. Ensured backward compatibility
with `net8.0` and `net9.0`.
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -1,7 +1,7 @@
 ## General
 
 - Make only high confidence suggestions when reviewing code changes.
-- Always use the latest version C#, currently C# 13 features.
+- Always use the latest version C#, currently C# 14 features.
 - Write code that is clean, maintainable, and easy to understand.
 - Only add comments rarely to explain why a non-intuitive solution was used. The code should be self-explanatory otherwise.
 - Don't add the UTF-8 BOM to files unless they have non-ASCII characters.
diff --git a/samples/Controllers/ApiKeySample/ApiKeySample.csproj b/samples/Controllers/ApiKeySample/ApiKeySample.csproj
@@ -1,14 +1,14 @@
 ﻿<Project Sdk="Microsoft.NET.Sdk.Web">
 
     <PropertyGroup>
-        <TargetFramework>net9.0</TargetFramework>
+        <TargetFramework>net10.0</TargetFramework>
         <Nullable>enable</Nullable>
         <ImplicitUsings>enable</ImplicitUsings>
     </PropertyGroup>
 
     <ItemGroup>
-        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.10" />
-        <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="9.0.6" />
+        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
+        <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
     </ItemGroup>
 
     <ItemGroup>
diff --git a/samples/Controllers/BasicAuthenticationSample/BasicAuthenticationSample.csproj b/samples/Controllers/BasicAuthenticationSample/BasicAuthenticationSample.csproj
@@ -1,14 +1,14 @@
 ﻿<Project Sdk="Microsoft.NET.Sdk.Web">
 
     <PropertyGroup>
-        <TargetFramework>net9.0</TargetFramework>
+        <TargetFramework>net10.0</TargetFramework>
         <Nullable>enable</Nullable>
         <ImplicitUsings>enable</ImplicitUsings>
     </PropertyGroup>
 
     <ItemGroup>
-        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.10" />
-        <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="9.0.6" />
+        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
+        <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
     </ItemGroup>
 
     <ItemGroup>
diff --git a/samples/Controllers/JwtBearerSample/JwtBearerSample.csproj b/samples/Controllers/JwtBearerSample/JwtBearerSample.csproj
@@ -1,14 +1,14 @@
 ﻿<Project Sdk="Microsoft.NET.Sdk.Web">
 
     <PropertyGroup>
-        <TargetFramework>net9.0</TargetFramework>
+        <TargetFramework>net10.0</TargetFramework>
         <Nullable>enable</Nullable>
         <ImplicitUsings>enable</ImplicitUsings>
     </PropertyGroup>
 
     <ItemGroup>
-        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.10" />
-        <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="9.0.6" />
+        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
+        <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
     </ItemGroup>
 
     <ItemGroup>
diff --git a/samples/MinimalApis/ApiKeySample/ApiKeySample.csproj b/samples/MinimalApis/ApiKeySample/ApiKeySample.csproj
@@ -1,18 +1,17 @@
 ﻿<Project Sdk="Microsoft.NET.Sdk.Web">
 
     <PropertyGroup>
-        <TargetFramework>net9.0</TargetFramework>
+        <TargetFramework>net10.0</TargetFramework>
         <Nullable>enable</Nullable>
         <ImplicitUsings>enable</ImplicitUsings>
     </PropertyGroup>
 
     <ItemGroup>
-        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.10" />
-        <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="9.0.6" />
+        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
+        <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
     </ItemGroup>
 
     <ItemGroup>
-        <ProjectReference Include="..\..\..\src\SimpleAuthentication.Swashbuckle\SimpleAuthentication.Swashbuckle.csproj" />
         <ProjectReference Include="..\..\..\src\SimpleAuthentication\SimpleAuthentication.csproj" />
     </ItemGroup>
 
diff --git a/samples/MinimalApis/BasicAuthenticationSample/BasicAuthenticationSample.csproj b/samples/MinimalApis/BasicAuthenticationSample/BasicAuthenticationSample.csproj
@@ -1,18 +1,17 @@
 ﻿<Project Sdk="Microsoft.NET.Sdk.Web">
 
     <PropertyGroup>
-        <TargetFramework>net9.0</TargetFramework>
+        <TargetFramework>net10.0</TargetFramework>
         <Nullable>enable</Nullable>
         <ImplicitUsings>enable</ImplicitUsings>
     </PropertyGroup>
 
     <ItemGroup>
-        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.10" />
-        <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="9.0.6" />
+        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
+        <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
     </ItemGroup>
 
     <ItemGroup>
-        <ProjectReference Include="..\..\..\src\SimpleAuthentication.Swashbuckle\SimpleAuthentication.Swashbuckle.csproj" />
         <ProjectReference Include="..\..\..\src\SimpleAuthentication\SimpleAuthentication.csproj" />
     </ItemGroup>
 
diff --git a/samples/MinimalApis/JwtBearerSample/JwtBearerSample.csproj b/samples/MinimalApis/JwtBearerSample/JwtBearerSample.csproj
@@ -1,14 +1,14 @@
 ﻿<Project Sdk="Microsoft.NET.Sdk.Web">
 
     <PropertyGroup>
-        <TargetFramework>net9.0</TargetFramework>
+        <TargetFramework>net10.0</TargetFramework>
         <Nullable>enable</Nullable>
         <ImplicitUsings>enable</ImplicitUsings>
     </PropertyGroup>
 
     <ItemGroup>
-        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.10" />
-        <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="9.0.6" />
+        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
+        <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
     </ItemGroup>
 
     <ItemGroup>
diff --git a/samples/MinimalApis/Net8JwtBearerSample/Net8JwtBearerSample.csproj b/samples/MinimalApis/Net8JwtBearerSample/Net8JwtBearerSample.csproj
@@ -7,7 +7,7 @@
     </PropertyGroup>
 
     <ItemGroup>
-        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="[8.0.21,9.0.0)" />
+        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="[8.0.22,9.0.0)" />
         <PackageReference Include="Swashbuckle.AspNetCore" Version="9.0.6" />
     </ItemGroup>
 
diff --git a/src/SimpleAuthentication.Abstractions/SimpleAuthentication.Abstractions.csproj b/src/SimpleAuthentication.Abstractions/SimpleAuthentication.Abstractions.csproj
@@ -1,7 +1,7 @@
 ﻿<Project Sdk="Microsoft.NET.Sdk">
 
     <PropertyGroup>
-        <TargetFrameworks>net8.0;net9.0</TargetFrameworks>
+        <TargetFrameworks>net8.0;net9.0;net10.0</TargetFrameworks>
         <ImplicitUsings>enable</ImplicitUsings>
         <Nullable>enable</Nullable>
         <LangVersion>latest</LangVersion>
@@ -28,11 +28,15 @@
     </ItemGroup>
 
     <ItemGroup Condition="'$(TargetFramework)' == 'net8.0'">
-        <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="8.0.21" />
+        <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="8.0.22" />
     </ItemGroup>
 
     <ItemGroup Condition="'$(TargetFramework)' == 'net9.0'">
-        <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="9.0.10" />
+        <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="9.0.11" />
+    </ItemGroup>
+
+    <ItemGroup Condition="'$(TargetFramework)' == 'net10.0'">
+        <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.0" />
     </ItemGroup>
     
     <ItemGroup>
diff --git a/src/SimpleAuthentication.Swashbuckle/SimpleAuthentication.Swashbuckle.csproj b/src/SimpleAuthentication.Swashbuckle/SimpleAuthentication.Swashbuckle.csproj
@@ -32,7 +32,6 @@
     </ItemGroup>
 
     <ItemGroup>
-        <PackageReference Include="SimpleAuthenticationTools.Abstractions" Version="3.1.4" />
         <PackageReference Include="Swashbuckle.AspNetCore.SwaggerGen" Version="9.0.6" />
     </ItemGroup>
 
@@ -43,5 +42,9 @@
         </None>
         <None Include="..\..\README.md" Pack="true" PackagePath="\" />
     </ItemGroup>
+
+    <ItemGroup>
+      <ProjectReference Include="..\SimpleAuthentication.Abstractions\SimpleAuthentication.Abstractions.csproj" />
+    </ItemGroup>
     
 </Project>
diff --git a/src/SimpleAuthentication/OpenApi/AuthenticationDocumentTransformer.cs b/src/SimpleAuthentication/OpenApi/AuthenticationDocumentTransformer.cs
@@ -1,4 +1,4 @@
-﻿#if NET9_0_OR_GREATER
+﻿#if NET9_0
 
 using Microsoft.AspNetCore.Authentication.JwtBearer;
 using Microsoft.AspNetCore.OpenApi;
@@ -106,4 +106,122 @@ private static void AddSecurityRequirement(OpenApiDocument document, OpenApiSecu
     }
 }
 
+#elif NET10_0_OR_GREATER
+
+using System.Xml.Linq;
+using Microsoft.AspNetCore.Authentication.JwtBearer;
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Net.Http.Headers;
+using Microsoft.OpenApi;
+using SimpleAuthentication.ApiKey;
+using SimpleAuthentication.BasicAuthentication;
+using SimpleAuthentication.JwtBearer;
+
+namespace SimpleAuthentication.OpenApi;
+
+internal class AuthenticationDocumentTransformer(IConfiguration configuration, string sectionName, IEnumerable<OpenApiSecurityRequirement> additionalSecurityRequirements, IEnumerable<string> additionalSecurityDefinitionNames) : IOpenApiDocumentTransformer
+{
+    public Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
+    {
+        // Adds a security definition for each authentication method that has been configured.
+        CheckAddJwtBearer(document, configuration.GetSection($"{sectionName}:JwtBearer"));
+        CheckAddApiKey(document, configuration.GetSection($"{sectionName}:ApiKey"));
+        CheckAddBasicAuthentication(document, configuration.GetSection($"{sectionName}:Basic"));
+
+        if (additionalSecurityRequirements.Any())
+        {
+            // Adds all the other security requirements that have been specified.
+            foreach (var securityRequirement in additionalSecurityRequirements)
+            {
+                AddSecurityRequirement(document, securityRequirement);
+            }
+        }
+
+        if (additionalSecurityDefinitionNames.Any())
+        {
+            // Adds all the other security definitions that have been specified.
+            foreach (var definitionName in additionalSecurityDefinitionNames)
+            {
+                AddSecurityRequirement(document, definitionName);
+            }
+        }
+
+        return Task.CompletedTask;
+
+        static void CheckAddJwtBearer(OpenApiDocument document, IConfigurationSection section)
+        {
+            var settings = section.Get<JwtBearerSettings>();
+            if (settings is null)
+            {
+                return;
+            }
+
+            AddSecurityScheme(document, settings.SchemeName, SecuritySchemeType.Http, JwtBearerDefaults.AuthenticationScheme, ParameterLocation.Header, HeaderNames.Authorization, "Insert the Bearer Token");
+            AddSecurityRequirement(document, settings.SchemeName);
+        }
+
+        static void CheckAddApiKey(OpenApiDocument document, IConfigurationSection section)
+        {
+            var settings = section.Get<ApiKeySettings>();
+            if (settings is null)
+            {
+                return;
+            }
+
+            if (!string.IsNullOrWhiteSpace(settings.HeaderName))
+            {
+                var schemeName = $"{settings.SchemeName}-Header";
+
+                AddSecurityScheme(document, schemeName, SecuritySchemeType.ApiKey, null, ParameterLocation.Header, settings.HeaderName, "Insert the API Key");
+                AddSecurityRequirement(document, schemeName);
+            }
+
+            if (!string.IsNullOrWhiteSpace(settings.QueryStringKey))
+            {
+                var schemeName = $"{settings.SchemeName}-QueryString";
+
+                AddSecurityScheme(document, schemeName, SecuritySchemeType.ApiKey, null, ParameterLocation.Query, settings.QueryStringKey, "Insert the API Key");
+                AddSecurityRequirement(document, schemeName);
+            }
+        }
+
+        static void CheckAddBasicAuthentication(OpenApiDocument document, IConfigurationSection section)
+        {
+            var settings = section.Get<BasicAuthenticationSettings>();
+            if (settings is null)
+            {
+                return;
+            }
+
+            AddSecurityScheme(document, settings.SchemeName, SecuritySchemeType.Http, BasicAuthenticationDefaults.AuthenticationScheme, ParameterLocation.Header, HeaderNames.Authorization, "Insert user name and password");
+            AddSecurityRequirement(document, settings.SchemeName);
+        }
+    }
+
+    private static void AddSecurityScheme(OpenApiDocument document, string name, SecuritySchemeType securitySchemeType, string? scheme, ParameterLocation location, string parameterName, string description)
+    {
+        document.Components ??= new();
+        document.Components.SecuritySchemes ??= new Dictionary<string, IOpenApiSecurityScheme>();
+
+        document.Components.SecuritySchemes.Add(name, new OpenApiSecurityScheme()
+        {
+            In = location,
+            Name = parameterName,
+            Description = description,
+            Type = securitySchemeType,
+            Scheme = scheme
+        });
+    }
+
+    internal static void AddSecurityRequirement(OpenApiDocument document, string name)
+        => AddSecurityRequirement(document, OpenApiHelpers.CreateSecurityRequirement(name, document));
+
+    private static void AddSecurityRequirement(OpenApiDocument document, OpenApiSecurityRequirement requirement)
+    {
+        document.Security ??= [];
+        document.Security.Add(requirement);
+    }
+}
+
 #endif
diff --git a/src/SimpleAuthentication/OpenApi/AuthenticationOperationTransformer.cs b/src/SimpleAuthentication/OpenApi/AuthenticationOperationTransformer.cs
@@ -1,4 +1,4 @@
-﻿#if NET9_0_OR_GREATER
+﻿#if NET9_0
 
 using System.Net;
 using Microsoft.AspNetCore.Authorization;
@@ -30,4 +30,37 @@ public async Task TransformAsync(OpenApiOperation operation, OpenApiOperationTra
     }
 }
 
+#elif NET10_0_OR_GREATER
+
+using System.Net;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Authorization.Infrastructure;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.OpenApi;
+
+namespace SimpleAuthentication.OpenApi;
+
+internal class AuthenticationOperationTransformer(IAuthorizationPolicyProvider authorizationPolicyProvider) : IOpenApiOperationTransformer
+{
+    public async Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransformerContext context, CancellationToken cancellationToken)
+    {
+        // If the method requires authorization, automatically add 401 and 403 response (if not explicitly specified).
+        var fallbackPolicy = await authorizationPolicyProvider.GetFallbackPolicyAsync();
+        var requireAuthenticatedUser = fallbackPolicy?.Requirements.Any(r => r is DenyAnonymousAuthorizationRequirement) ?? false;
+
+        var endpointMetadata = context.Description.ActionDescriptor.EndpointMetadata;
+
+        var requireAuthorization = endpointMetadata.Any(m => m is AuthorizeAttribute);
+        var allowAnonymous = endpointMetadata.Any(m => m is AllowAnonymousAttribute);
+
+        if ((requireAuthenticatedUser || requireAuthorization) && !allowAnonymous)
+        {
+            operation.Responses ??= [];
+            operation.Responses.TryAdd(StatusCodes.Status401Unauthorized.ToString(), OpenApiHelpers.CreateResponse(HttpStatusCode.Unauthorized.ToString()));
+            operation.Responses.TryAdd(StatusCodes.Status403Forbidden.ToString(), OpenApiHelpers.CreateResponse(HttpStatusCode.Forbidden.ToString()));
+        }
+    }
+}
+
 #endif
diff --git a/src/SimpleAuthentication/OpenApi/DefaultResponseDocumentTransformer.cs b/src/SimpleAuthentication/OpenApi/DefaultResponseDocumentTransformer.cs
@@ -1,4 +1,4 @@
-﻿#if NET9_0_OR_GREATER
+﻿#if NET9_0
 
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.AspNetCore.OpenApi;
@@ -60,4 +60,23 @@ public Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerC
     }
 }
 
+#elif NET10_0_OR_GREATER
+
+using System.Net.Mime;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.OpenApi;
+
+namespace SimpleAuthentication.OpenApi;
+
+internal class DefaultResponseDocumentTransformer : IOpenApiDocumentTransformer
+{
+    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
+    {
+        // Generate schema for error responses.
+        var errorSchema = await context.GetOrCreateSchemaAsync(typeof(ProblemDetails), cancellationToken: cancellationToken);
+        document.AddComponent(nameof(ProblemDetails), errorSchema);
+    }
+}
+
 #endif
diff --git a/src/SimpleAuthentication/OpenApi/OAuth2AuthenticationDocumentTransformer.cs b/src/SimpleAuthentication/OpenApi/OAuth2AuthenticationDocumentTransformer.cs
diff --git a/src/SimpleAuthentication/OpenApi/OpenApiHelpers.cs b/src/SimpleAuthentication/OpenApi/OpenApiHelpers.cs
diff --git a/src/SimpleAuthentication/OpenApiExtensions.cs b/src/SimpleAuthentication/OpenApiExtensions.cs
diff --git a/src/SimpleAuthentication/SimpleAuthentication.csproj b/src/SimpleAuthentication/SimpleAuthentication.csproj
