Upgrade OpenAPI and Swashbuckle dependencies

Updated project files to upgrade `Swashbuckle.AspNetCore` to v10.0.0 and align with OpenAPI 3.1. Refactored `Program.cs` to use `.WithDescription()` for better readability. Added `net10.0` support in `SimpleAuthentication.Swashbuckle.csproj`.

Replaced `Microsoft.OpenApi.Models` with `Microsoft.OpenApi` across multiple files to align with updated libraries. Refactored `SwaggerExtensions.cs` to improve flexibility and maintainability by introducing helper methods and supporting additional security definitions.

Upgraded `Nerdbank.GitVersioning` to v3.9.50 and made general improvements to simplify OpenAPI constructs and enhance compatibility with newer library versions.

Author: marcominerva

samples/MinimalApis/Net8JwtBearerSample/Net8JwtBearerSample.csproj

@@ -7,8 +7,8 @@
     </PropertyGroup>
 
     <ItemGroup>
-        <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="[8.0.22,9.0.0)" />
-        <PackageReference Include="Swashbuckle.AspNetCore" Version="9.0.6" />
+      <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.22" />
+      <PackageReference Include="Swashbuckle.AspNetCore" Version="10.0.0" />
     </ItemGroup>
 
     <ItemGroup>

samples/MinimalApis/Net8JwtBearerSample/Program.cs

@@ -2,6 +2,7 @@
 using JwtBearerSample.Authentication;
 using Microsoft.AspNetCore.Authentication;
 using Microsoft.AspNetCore.Http.HttpResults;
+using Microsoft.OpenApi;
 using SimpleAuthentication;
 using SimpleAuthentication.JwtBearer;
 using SimpleAuthentication.Permissions;
@@ -57,7 +58,11 @@
 app.UseExceptionHandler();
 app.UseStatusCodePages();
 
-app.UseSwagger();
+app.UseSwagger(options =>
+{
+    options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_1;
+});
+
 app.UseSwaggerUI();
 
 app.UseAuthentication();
@@ -79,11 +84,7 @@
     var token = await jwtBearerService.CreateTokenAsync(loginRequest.UserName, claims, absoluteExpiration: expiration);
     return TypedResults.Ok(new LoginResponse(token));
 })
-.WithOpenApi(operation =>
-{
-    operation.Description = "Insert permissions in the scope property (for example: 'profile people:admin')";
-    return operation;
-});
+.WithDescription("Insert permissions in the scope property (for example: 'profile people:admin')");
 
 authApiGroup.MapPost("validate", async Task<Results<Ok<User>, BadRequest>> (string token, bool validateLifetime, IJwtBearerService jwtBearerService) =>
 {
@@ -95,38 +96,28 @@
     }
 
     return TypedResults.Ok(new User(result.Principal.Identity!.Name));
-})
-.WithOpenApi();
+});
 
 authApiGroup.MapPost("refresh", async (string token, bool validateLifetime, DateTime? expiration, IJwtBearerService jwtBearerService) =>
 {
     var newToken = await jwtBearerService.RefreshTokenAsync(token, validateLifetime, expiration);
     return TypedResults.Ok(new LoginResponse(newToken));
-})
-.WithOpenApi();
+});
 
 app.MapGet("api/me", (ClaimsPrincipal user) =>
 {
     return TypedResults.Ok(new User(user.Identity!.Name));
 })
 .RequireAuthorization()
 .RequirePermission("profile")
-.WithOpenApi(operation =>
-{
-    operation.Description = "This endpoint requires the 'profile' permission";
-    return operation;
-});
+.WithDescription("This endpoint requires the 'profile' permission");
 
 app.MapGet("api/people", () =>
 {
     return TypedResults.NoContent();
 })
 .RequireAuthorization(policyNames: "PeopleRead")
-.WithOpenApi(operation =>
-{
-    operation.Description = $"This endpoint requires the '{Permissions.PeopleRead}' or '{Permissions.PeopleAdmin}' permissions";
-    return operation;
-});
+.WithDescription($"This endpoint requires the '{Permissions.PeopleRead}' or '{Permissions.PeopleAdmin}' permissions");
 
 app.Run();
 

src/Directory.Build.props

@@ -9,7 +9,7 @@
     </PropertyGroup>
 
     <ItemGroup>
-        <PackageReference Include="Nerdbank.GitVersioning" Version="3.8.118"  PrivateAssets="All" />
+        <PackageReference Include="Nerdbank.GitVersioning" Version="3.9.50"  PrivateAssets="All" />
     </ItemGroup>
 
 </Project>

src/SimpleAuthentication.Swashbuckle/SimpleAuthentication.Swashbuckle.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>
@@ -31,10 +31,6 @@
         <FrameworkReference Include="Microsoft.AspNetCore.App" />
     </ItemGroup>
 
-    <ItemGroup>
-        <PackageReference Include="Swashbuckle.AspNetCore.SwaggerGen" Version="9.0.6" />
-    </ItemGroup>
-
     <ItemGroup>
         <None Include="..\..\Toolbox.png">
             <Pack>True</Pack>
@@ -43,6 +39,10 @@
         <None Include="..\..\README.md" Pack="true" PackagePath="\" />
     </ItemGroup>
 
+    <ItemGroup>
+      <PackageReference Include="Swashbuckle.AspNetCore.SwaggerGen" Version="10.0.0" />
+    </ItemGroup>
+
     <ItemGroup>
       <ProjectReference Include="..\SimpleAuthentication.Abstractions\SimpleAuthentication.Abstractions.csproj" />
     </ItemGroup>

src/SimpleAuthentication.Swashbuckle/Swagger/AuthenticationOperationFilter.cs

@@ -2,7 +2,7 @@
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Authorization.Infrastructure;
 using Microsoft.AspNetCore.Http;
-using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi;
 using Swashbuckle.AspNetCore.SwaggerGen;
 
 namespace SimpleAuthentication.Swagger;

src/SimpleAuthentication.Swashbuckle/Swagger/OpenApiHelpers.cs

@@ -1,25 +1,15 @@
 using System.Net.Mime;
 using Microsoft.AspNetCore.Mvc;
-using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi;
 
 namespace SimpleAuthentication.Swagger;
 
 internal static class OpenApiHelpers
 {
-    public static OpenApiSecurityRequirement CreateSecurityRequirement(string name)
+    public static OpenApiSecurityRequirement CreateSecurityRequirement(string name, OpenApiDocument document)
         => new()
             {
-                {
-                    new()
-                    {
-                        Reference = new()
-                        {
-                            Type = ReferenceType.SecurityScheme,
-                            Id = name
-                        }
-                    },
-                    []
-                }
+                { new OpenApiSecuritySchemeReference(name, document), [] }
             };
 
     public static OpenApiResponse CreateResponse(string description)
@@ -30,7 +20,7 @@ public static OpenApiResponse CreateResponse(string description)
             {
                 [MediaTypeNames.Application.ProblemJson] = new()
                 {
-                    Schema = new()
+                    Schema = new OpenApiSchemaReference(nameof(ProblemDetails))
                     {
                         Reference = new()
                         {

src/SimpleAuthentication.Swashbuckle/Swagger/ProblemDetailsDocumentFilter.cs

@@ -1,5 +1,5 @@
 using Microsoft.AspNetCore.Mvc;
-using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi;
 using Swashbuckle.AspNetCore.SwaggerGen;
 
 namespace SimpleAuthentication.Swagger;

src/SimpleAuthentication.Swashbuckle/SwaggerExtensions.cs

@@ -2,7 +2,7 @@
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Net.Http.Headers;
-using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi;
 using SimpleAuthentication.ApiKey;
 using SimpleAuthentication.BasicAuthentication;
 using SimpleAuthentication.JwtBearer;
@@ -25,7 +25,7 @@ public static class SwaggerExtensions
     /// <seealso cref="SwaggerGenOptions"/>
     /// <seealso cref="IConfiguration"/>
     public static void AddSimpleAuthentication(this SwaggerGenOptions options, IConfiguration configuration, string sectionName = "Authentication")
-        => options.AddSimpleAuthentication(configuration, sectionName, Array.Empty<OpenApiSecurityRequirement>());
+        => options.AddSimpleAuthentication(configuration, sectionName, [], []);
 
     /// <summary>
     /// Adds authentication support in Swagger, enabling the Authorize button in the Swagger UI, reading configuration from a section named <strong>Authentication</strong> in <see cref="IConfiguration"/> source.
@@ -35,7 +35,7 @@ public static void AddSimpleAuthentication(this SwaggerGenOptions options, IConf
     /// <param name="additionalSecurityDefinitionNames">The name of additional security definitions that have been defined in Swagger.</param>
     /// <seealso cref="SwaggerGenOptions"/>
     /// <seealso cref="IConfiguration"/>
-    public static void AddSimpleAuthentication(this SwaggerGenOptions options, IConfiguration configuration, IEnumerable<string>? additionalSecurityDefinitionNames)
+    public static void AddSimpleAuthentication(this SwaggerGenOptions options, IConfiguration configuration, params IEnumerable<string> additionalSecurityDefinitionNames)
         => options.AddSimpleAuthentication(configuration, "Authentication", additionalSecurityDefinitionNames);
 
     /// <summary>
@@ -47,11 +47,7 @@ public static void AddSimpleAuthentication(this SwaggerGenOptions options, IConf
     /// <param name="additionalSecurityDefinitionNames">The name of additional security definitions that have been defined in Swagger.</param>
     /// <seealso cref="SwaggerGenOptions"/>
     /// <seealso cref="IConfiguration"/>
-    public static void AddSimpleAuthentication(this SwaggerGenOptions options, IConfiguration configuration, string sectionName, IEnumerable<string>? additionalSecurityDefinitionNames)
-    {
-        var securityRequirements = additionalSecurityDefinitionNames?.Select(OpenApiHelpers.CreateSecurityRequirement).ToArray();
-        options.AddSimpleAuthentication(configuration, sectionName, securityRequirements ?? []);
-    }
+    public static void AddSimpleAuthentication(this SwaggerGenOptions options, IConfiguration configuration, string sectionName, params IEnumerable<string> additionalSecurityDefinitionNames) => options.AddSimpleAuthentication(configuration, sectionName, [], additionalSecurityDefinitionNames);
 
     /// <summary>
     /// Adds authentication support in Swagger, enabling the Authorize button in the Swagger UI, reading configuration from the specified <see cref="IConfiguration"/> source.
@@ -61,8 +57,8 @@ public static void AddSimpleAuthentication(this SwaggerGenOptions options, IConf
     /// <param name="securityRequirements">Additional security requirements to be added to Swagger definition.</param>
     /// <seealso cref="SwaggerGenOptions"/>
     /// <seealso cref="IConfiguration"/>
-    public static void AddSimpleAuthentication(this SwaggerGenOptions options, IConfiguration configuration, params OpenApiSecurityRequirement[] securityRequirements)
-        => options.AddSimpleAuthentication(configuration, "Authentication", securityRequirements);
+    public static void AddSimpleAuthentication(this SwaggerGenOptions options, IConfiguration configuration, params IEnumerable<OpenApiSecurityRequirement> securityRequirements)
+        => options.AddSimpleAuthentication(configuration, "Authentication", securityRequirements, []);
 
     /// <summary>
     /// Adds authentication support in Swagger, enabling the Authorize button in the Swagger UI, reading configuration from the specified <see cref="IConfiguration"/> source.
@@ -71,9 +67,10 @@ public static void AddSimpleAuthentication(this SwaggerGenOptions options, IConf
     /// <param name="configuration">The <see cref="IConfiguration"/> being bound.</param>
     /// <param name="sectionName">The name of the configuration section that holds authentication settings (default: Authentication).</param>
     /// <param name="additionalSecurityRequirements">Additional security requirements to be added to Swagger definition.</param>
+    /// <param name="additionalSecurityDefinitionNames">The name of additional security definitions that have been defined in OpenAPI.</param>
     /// <seealso cref="SwaggerGenOptions"/>
     /// <seealso cref="IConfiguration"/>
-    public static void AddSimpleAuthentication(this SwaggerGenOptions options, IConfiguration configuration, string sectionName, params OpenApiSecurityRequirement[] additionalSecurityRequirements)
+    public static void AddSimpleAuthentication(this SwaggerGenOptions options, IConfiguration configuration, string sectionName, IEnumerable<OpenApiSecurityRequirement> additionalSecurityRequirements, IEnumerable<string> additionalSecurityDefinitionNames)
     {
         ArgumentNullException.ThrowIfNull(options);
         ArgumentNullException.ThrowIfNull(configuration);
@@ -84,12 +81,21 @@ public static void AddSimpleAuthentication(this SwaggerGenOptions options, IConf
         CheckAddApiKey(options, configuration.GetSection($"{sectionName}:ApiKey"));
         CheckAddBasicAuthentication(options, configuration.GetSection($"{sectionName}:Basic"));
 
-        if (additionalSecurityRequirements?.Any() ?? false)
+        if (additionalSecurityRequirements?.Any() == true)
         {
             // Adds all the other security requirements that have been specified.
             foreach (var securityRequirement in additionalSecurityRequirements)
             {
-                options.AddSecurityRequirement(securityRequirement);
+                AddSecurityRequirement(options, securityRequirement);
+            }
+        }
+
+        if (additionalSecurityDefinitionNames?.Any() == true)
+        {
+            // Adds all the other security definitions that have been specified.
+            foreach (var definitionName in additionalSecurityDefinitionNames)
+            {
+                AddSecurityRequirement(options, definitionName);
             }
         }
 
@@ -146,7 +152,7 @@ static void CheckAddBasicAuthentication(SwaggerGenOptions options, IConfiguratio
         }
 
         static void AddSecurityDefinition(SwaggerGenOptions options, string name, SecuritySchemeType securitySchemeType, string? scheme, ParameterLocation location, string parameterName, string description)
-            => options.AddSecurityDefinition(name, new()
+            => options.AddSecurityDefinition(name, new OpenApiSecurityScheme()
             {
                 In = location,
                 Name = parameterName,
@@ -195,7 +201,7 @@ public static void AddOAuth2Authentication(this SwaggerGenOptions options, strin
         ArgumentException.ThrowIfNullOrWhiteSpace(name);
         ArgumentNullException.ThrowIfNull(authFlow);
 
-        options.AddSecurityDefinition(name, new()
+        options.AddSecurityDefinition(name, new OpenApiSecurityScheme()
         {
             Type = SecuritySchemeType.OAuth2,
             Flows = new()
@@ -207,6 +213,9 @@ public static void AddOAuth2Authentication(this SwaggerGenOptions options, strin
         AddSecurityRequirement(options, name);
     }
 
+    private static void AddSecurityRequirement(SwaggerGenOptions options, OpenApiSecurityRequirement requirement)
+        => options.AddSecurityRequirement(_ => requirement);
+
     private static void AddSecurityRequirement(SwaggerGenOptions options, string name)
-        => options.AddSecurityRequirement(OpenApiHelpers.CreateSecurityRequirement(name));
+        => options.AddSecurityRequirement(document => OpenApiHelpers.CreateSecurityRequirement(name, document));
 }