add open api support

Author: pwelter34

AspNetCore.SecurityKey.sln

@@ -32,6 +32,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Sample.Middleware", "sample
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Sample.Shared", "samples\Sample.Shared\Sample.Shared.csproj", "{CF5ED041-2229-4481-8DCC-8BB4438B222C}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AspNetCore.SecurityKey.OpenApi", "src\AspNetCore.SecurityKey.OpenApi\AspNetCore.SecurityKey.OpenApi.csproj", "{D85383E1-69CE-4CC0-B65A-171E0B31F336}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -62,6 +64,10 @@ Global
 		{CF5ED041-2229-4481-8DCC-8BB4438B222C}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{CF5ED041-2229-4481-8DCC-8BB4438B222C}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{CF5ED041-2229-4481-8DCC-8BB4438B222C}.Release|Any CPU.Build.0 = Release|Any CPU
+		{D85383E1-69CE-4CC0-B65A-171E0B31F336}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{D85383E1-69CE-4CC0-B65A-171E0B31F336}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{D85383E1-69CE-4CC0-B65A-171E0B31F336}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{D85383E1-69CE-4CC0-B65A-171E0B31F336}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

README.md

@@ -180,3 +180,45 @@ public static class Program
     }
 }
 ```
+
+### Custom Security Key Validation
+
+You can implement your own custom security key validation by implementing the `ISecurityKeyValidator` interface.
+
+```c#
+public class CustomSecurityKeyValidator : ISecurityKeyValidator
+{
+    public Task<bool> ValidateAsync(HttpContext context, string key)
+    {
+        // custom validation logic
+        return Task.FromResult(true);
+    }
+}
+```
+
+Use custom security key validator
+
+```c#
+builder.Services.AddSecurityKey<CustomSecurityKeyValidator>();
+```
+
+### Custom Security Key Extractor
+
+You can implement your own custom security key extractor by implementing the `ISecurityKeyExtractor` interface.
+
+```c#
+public class CustomSecurityKeyExtractor : ISecurityKeyExtractor
+{
+    public Task<string> ExtractAsync(HttpContext context)
+    {
+        // custom extraction logic
+        return Task.FromResult("custom-key");
+    }
+}
+```
+
+Use custom security key validator and extrator
+
+```c#
+builder.Services.AddSecurityKey<CustomSecurityKeyValidator, CustomSecurityKeyExtractor>();
+```

samples/Sample.MinimalApi/Program.cs

@@ -1,9 +1,12 @@
 using System.Security.Claims;
 
 using AspNetCore.SecurityKey;
+using AspNetCore.SecurityKey.OpenApi;
 
 using Sample.Shared;
 
+using Scalar.AspNetCore;
+
 namespace Sample.MinimalApi;
 
 public static class Program
@@ -20,14 +23,11 @@ public static void Main(string[] args)
 
         builder.Services.AddSecurityKey();
 
+        builder.Services.AddOpenApi(options => options.AddDocumentTransformer<SecurityKeyDocumentTransformer>());
         builder.Services.AddEndpointsApiExplorer();
-        builder.Services.AddSwaggerGen();
 
         var app = builder.Build();
 
-        app.UseSwagger();
-        app.UseSwaggerUI();
-
         app.UseHttpsRedirection();
 
         app.UseAuthentication();
@@ -58,6 +58,9 @@ public static void Main(string[] args)
             .WithName("GetCurrentUser")
             .WithOpenApi();
 
+        app.MapOpenApi();
+        app.MapScalarApiReference();
+
         app.Run();
     }
 }

samples/Sample.MinimalApi/Properties/launchSettings.json

@@ -5,7 +5,7 @@
       "commandName": "Project",
       "dotnetRunMessages": true,
       "launchBrowser": true,
-      "launchUrl": "swagger",
+      "launchUrl": "scalar/v1",
       "applicationUrl": "https://localhost:7216;http://localhost:5009",
       "environmentVariables": {
         "ASPNETCORE_ENVIRONMENT": "Development"

samples/Sample.MinimalApi/Sample.MinimalApi.csproj

@@ -7,17 +7,15 @@
   </PropertyGroup>
 
   <ItemGroup>
+    <PackageReference Update="Bogus" Version="35.6.3" />
     <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.4" />
-    <PackageReference Include="Swashbuckle.AspNetCore" Version="8.1.1" />
+    <PackageReference Include="Scalar.AspNetCore" Version="2.2.7" />
   </ItemGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\..\src\AspNetCore.SecurityKey.OpenApi\AspNetCore.SecurityKey.OpenApi.csproj" />
     <ProjectReference Include="..\..\src\AspNetCore.SecurityKey\AspNetCore.SecurityKey.csproj" />
     <ProjectReference Include="..\Sample.Shared\Sample.Shared.csproj" />
   </ItemGroup>
 
-  <ItemGroup>
-    <PackageReference Update="Bogus" Version="35.6.3" />
-  </ItemGroup>
-
 </Project>

src/AspNetCore.SecurityKey.OpenApi/AspNetCore.SecurityKey.OpenApi.csproj

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.4" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\AspNetCore.SecurityKey\AspNetCore.SecurityKey.csproj" />
+  </ItemGroup>
+
+</Project>

src/AspNetCore.SecurityKey.OpenApi/SecurityKeyDocumentTransformer.cs

@@ -0,0 +1,64 @@
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.Extensions.Options;
+using Microsoft.OpenApi.Models;
+
+namespace AspNetCore.SecurityKey.OpenApi;
+
+/// <summary>
+/// A transformer that modifies the OpenAPI document to include security key authentication schemes.
+/// </summary>
+public class SecurityKeyDocumentTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider, IOptions<SecurityKeyOptions> securityKeyOptions)
+    : IOpenApiDocumentTransformer
+{
+    /// <summary>
+    /// Transforms the OpenAPI document to include security key authentication schemes.
+    /// </summary>
+    /// <param name="document">The OpenAPI document to transform.</param>
+    /// <param name="context">The context for the OpenAPI document transformation.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
+    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
+    {
+        var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
+
+        if (!authenticationSchemes.Any(authScheme => string.Equals(authScheme.Name, SecurityKeyAuthenticationDefaults.AuthenticationScheme, StringComparison.InvariantCultureIgnoreCase)))
+            return;
+
+        var headerName = securityKeyOptions.Value.HeaderName;
+
+        var openApiSecurityScheme1 = new OpenApiSecurityScheme
+        {
+            Type = SecuritySchemeType.ApiKey,
+            Scheme = SecurityKeyAuthenticationDefaults.AuthenticationScheme,
+            In = ParameterLocation.Header,
+            Name = headerName
+        };
+
+        var requirements = new Dictionary<string, OpenApiSecurityScheme>
+        {
+            ["API Key"] = openApiSecurityScheme1
+        };
+
+        document.Components ??= new OpenApiComponents();
+        document.Components.SecuritySchemes = requirements;
+
+        foreach (var operation in document.Paths.Values.SelectMany(path => path.Operations))
+        {
+            var openApiSecurityScheme = new OpenApiSecurityScheme
+            {
+                Reference = new OpenApiReference
+                {
+                    Id = "API Key",
+                    Type = ReferenceType.SecurityScheme
+                }
+            };
+            var requirement = new OpenApiSecurityRequirement
+            {
+                [openApiSecurityScheme] = Array.Empty<string>()
+            };
+
+            operation.Value.Security.Add(requirement);
+        }
+    }
+}