feat: support Microsoft.AspNetCore.OpenApi

Author: ascott18

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Features
 
+- Added support for .NET 9.
+- `IntelliTect.Coalesce.Swashbuckle` is now deprecated in favor of `Microsoft.AspNetCore.OpenApi` for .NET 9+ projects. To upgrade:
+  - Replace `services.AddSwaggerGen(...)` with `services.AddOpenApi()`.
+  - Replace `app.MapSwagger()` with `app.MapOpenApi()`.
+  - Replace `app.UseSwaggerUI()` with `app.MapScalarApiReference()` from package `Scalar.AspNetCore`. The OpenAPI UI maps to `/scalar/v1` by default.
 - Added a `reset` method to all [API caller objects](https://intellitect.github.io/Coalesce/stacks/vue/layers/api-clients.html#api-callers). This method resets all stateful fields on the object to default values.
 - Template: Added username/password auth option (aka individual user accounts, aka local accounts)
 

Directory.Packages.props

@@ -17,6 +17,7 @@
     <PackageVersion Include="McMaster.Extensions.CommandLineUtils" Version="2.3.0" />
     <PackageVersion Include="Microsoft.AspNetCore.Mvc.Testing" Version="$(DotNetPackageVersionSpec)" />
     <PackageVersion Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="$(DotNetPackageVersionSpec)" />
+    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="9.0.0" />
     <PackageVersion Include="Microsoft.AspNetCore.SpaServices.Extensions" Version="$(DotNetPackageVersionSpec)" />
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.8.0" />
     <PackageVersion Include="Microsoft.Data.SqlClient" Version="5.2.2" />
@@ -28,13 +29,15 @@
     <PackageVersion Include="Microsoft.EntityFrameworkCore.Sqlite" Version="$(DotNetPackageVersionSpec)" />
     <PackageVersion Include="Microsoft.EntityFrameworkCore.SqlServer" Version="$(DotNetPackageVersionSpec)" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
+    <PackageVersion Include="Microsoft.OpenApi" Version="1.6.22" />
     <PackageVersion Include="Microsoft.OpenApi.Readers" Version="1.6.22" />
     <PackageVersion Include="Moq" Version="4.20.72" />
     <PackageVersion Include="Moq.AutoMock" Version="3.5.0" />
     <PackageVersion Include="NETStandard.Library" Version="2.0.3" />
     <PackageVersion Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="8.0.4" />
     <PackageVersion Include="Pomelo.EntityFrameworkCore.MySql" Version="8.0.2" />
     <PackageVersion Include="Roslynator.Analyzers" Version="4.12.7" />
+    <PackageVersion Include="Scalar.AspNetCore" Version="1.2.36" />
     <PackageVersion Include="Swashbuckle.AspNetCore" Version="6.8.1" />
     <PackageVersion Include="System.Net.Http.Json" Version="8.0.1" />
     <PackageVersion Include="xunit" Version="2.9.2" />

playground/Coalesce.Domain/Case.cs

@@ -8,6 +8,7 @@
 using Microsoft.EntityFrameworkCore;
 using System;
 using System.Collections.Generic;
+using System.ComponentModel;
 using System.ComponentModel.DataAnnotations;
 using System.ComponentModel.DataAnnotations.Schema;
 using System.IO;
@@ -222,6 +223,7 @@ public class AllOpenCases : StandardDataSource<Case, AppDbContext>
             public AllOpenCases(CrudContext<AppDbContext> context) : base(context) { }
 
             [Coalesce]
+            [Description("Only include cases opened on or after this date")]
             public DateTimeOffset? MinDate { get; set; }
 
             public override IQueryable<Case> GetQuery(IDataSourceParameters parameters) => Db.Cases

playground/Coalesce.Web.Vue3/Api/Generated/CaseController.g.cs

@@ -9,9 +9,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <!--<PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="6.0.2" />
-    <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="6.0.3" />
-    <PackageReference Include="Pomelo.EntityFrameworkCore.MySql" Version="6.0.1" />-->
+    <PackageReference Include="Scalar.AspNetCore" />
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\Coalesce.Domain\Coalesce.Domain.csproj" />

playground/Coalesce.Web.Vue3/Coalesce.Web.Vue3.csproj

@@ -4,9 +4,11 @@
 using Microsoft.AspNetCore.Authentication;
 using Microsoft.AspNetCore.Authentication.Cookies;
 using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging.Console;
 using Microsoft.Net.Http.Headers;
 using Microsoft.OpenApi.Models;
+using Scalar.AspNetCore;
 using System.Security.Claims;
 using System.Text.Json;
 using System.Text.Json.Serialization;
@@ -59,7 +61,7 @@
 });
 
 
-//services.AddOpenApi(); // net9
+services.AddOpenApi();
 
 services.AddSwaggerGen(c =>
 {
@@ -119,7 +121,10 @@
 
 app.UseCors(c => c.AllowAnyOrigin().AllowAnyHeader());
 app.MapControllers();
-//app.MapOpenApi(); // net9
+
+app.MapOpenApi();
+app.MapScalarApiReference();
+
 app.MapSwagger();
 app.UseSwaggerUI(c =>
 {

playground/Coalesce.Web.Vue3/Program.cs

@@ -20,7 +20,8 @@
       <v-btn variant="text" to="/test">Test</v-btn>
       <v-btn variant="text" to="/test-setup">Test2</v-btn>
       <v-btn variant="text" to="/audit-logs">Audit</v-btn>
-      <v-btn variant="text" to="/swagger">OpenAPI</v-btn>
+      <v-btn variant="text" href="/swagger">Swagger</v-btn>
+      <v-btn variant="text" href="/scalar/v1">OpenAPI</v-btn>
       <v-btn variant="text" href="/coalesce-security">Security Overview</v-btn>
 
       <v-menu offset-y>

playground/Coalesce.Web.Vue3/src/App.vue

@@ -8,6 +8,7 @@
 using Swashbuckle.AspNetCore.Swagger;
 using Swashbuckle.AspNetCore.SwaggerGen;
 using System;
+using System.Collections.Generic;
 using System.Linq;
 
 namespace IntelliTect.Coalesce.Swashbuckle
@@ -126,46 +127,40 @@ private void ProcessStandardParameters(OpenApiOperation operation, MethodViewMod
 
         private void ProcessDataSources(OpenApiOperation operation, OperationFilterContext context, MethodViewModel method)
         {
-            // In all reality, there will only ever be one data source parameter per action,
-            // but might as well not make assumptions if we don't have to.
-            foreach (var paramVm in method.Parameters.Where(p => p.Type.IsA(typeof(IDataSource<>))))
-            {
-                var declaredFor =
-                    paramVm.GetAttributeValue<DeclaredForAttribute>(a => a.DeclaredFor)
-                    ?? paramVm.Type.GenericArgumentsFor(typeof(IDataSource<>))!.Single();
+            var iDataSourceParam = method.Parameters.FirstOrDefault(p => p.Type.IsA(typeof(IDataSource<>)));
+            if (iDataSourceParam is null) return;
+
+            var declaredFor =
+                iDataSourceParam.GetAttributeValue<DeclaredForAttribute>(a => a.DeclaredFor)
+                ?? iDataSourceParam.Type.GenericArgumentsFor(typeof(IDataSource<>))!.Single();
 
-                var dataSources = declaredFor.ClassViewModel.ClientDataSources(reflectionRepository);
+            var dataSources = declaredFor.ClassViewModel!.ClientDataSources(reflectionRepository);
 
-                var dataSourceParam = new OpenApiParameter
+            var dataSourceNameParam = operation.Parameters.FirstOrDefault(p => p.Name == nameof(IDataSourceParameters.DataSource));
+            if (dataSourceNameParam is not null)
+            {
+                dataSourceNameParam.Schema = new OpenApiSchema
                 {
-                    In = ParameterLocation.Query,
-                    Name = paramVm.Name,
-                    Required = false,
-                    Schema = new OpenApiSchema
-                    {
-                        Type = "string",
-                        Enum = (new string[] { IntelliTect.Coalesce.Api.DataSources.DataSourceFactory.DefaultSourceName })
+                    Type = "string",
+                    Enum = (new string[] { IntelliTect.Coalesce.Api.DataSources.DataSourceFactory.DefaultSourceName })
                         .Concat(dataSources.Select(ds => ds.ClientTypeName))
                         .Select(n => new OpenApiString(n) as IOpenApiAny)
                         .ToList()
-                    },
                 };
-                operation.Parameters.Add(dataSourceParam);
 
-                foreach (var dataSource in dataSources)
+                foreach (var param in dataSources.SelectMany(ds => ds.DataSourceParameters).GroupBy(ds => ds.Name))
                 {
-                    foreach (var dsParam in dataSource.DataSourceParameters)
+                    var openApiParam = operation.Parameters.FirstOrDefault(p =>
+                        p.Name.Equals($"{dataSourceNameParam.Name}.{param.Key}", StringComparison.OrdinalIgnoreCase));
+
+                    if (openApiParam is not null)
                     {
-                        var schema = context.SchemaGenerator.GenerateSchema(dsParam.Type.TypeInfo, context.SchemaRepository);
+                        var dataSourceNames = string.Join(", ", param.Select(p => p.EffectiveParent.ClientTypeName));
 
-                        operation.Parameters.Add(new OpenApiParameter
+                        openApiParam.Description = string.Join(". \n", (new List<string>(param.Select(p => p.Description))
                         {
-                            In = ParameterLocation.Query,
-                            Name = $"{paramVm.Name}.{dsParam.Name}",
-                            Required = false,
-                            Description = $"Used by Data Source {dataSource.ClientTypeName}",
-                            Schema = schema,
-                        });
+                            $"Used by data source{(param.Count() == 1 ? "" : "s")} {dataSourceNames}."
+                        }).Where(s => !string.IsNullOrWhiteSpace(s)).Distinct());
                     }
                 }
             }

src/IntelliTect.Coalesce.Swashbuckle/CoalesceApiOperationFilter.cs

@@ -1,23 +1,16 @@
-using IntelliTect.Coalesce.Models;
-using IntelliTect.Coalesce.TypeDefinition;
-using Microsoft.AspNetCore.Mvc;
+using IntelliTect.Coalesce.TypeDefinition;
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
 using Microsoft.AspNetCore.Mvc.Controllers;
 using Microsoft.AspNetCore.Mvc.ModelBinding;
-using Microsoft.AspNetCore.Mvc.ModelBinding.Metadata;
-using System;
-using System.Collections.Generic;
 using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
 
 namespace IntelliTect.Coalesce.Api
 {
     /// <summary>
     /// Performs adjustments to the API metadata so that it doesn't cause .NET 9's OpenAPI generation to implode.
     /// In particular, we have to remove the parameters that are bound with Coalesce's custom model binders,
     /// since these cause the OpenAPI generator to throw exceptions. We re-add these definitions with
-    /// CoalesceApiOperationFilter (for Swashbuckle), or CLASS_TBD for the native aspnetcore OpenApi gen.
+    /// CoalesceApiOperationFilter.
     /// </summary>
     internal class CoalesceApiDescriptionProvider(ReflectionRepository reflectionRepository) : IApiDescriptionProvider
     {
@@ -50,7 +43,6 @@ private void ProcessStandardParameters(ApiDescription operation, MethodViewModel
             // We add them back in in CoalesceApiOperationFilter.
             // They break the new Microsoft.AspNetCore.OpenApi package in .NET 9
             // if we leave them present in the API descriptions.
-
             foreach (var paramVm in method.Parameters.Where(p =>
                 p.Type.IsA(typeof(IBehaviors<>)) || 
                 p.Type.IsA(typeof(IDataSource<>))
@@ -72,14 +64,35 @@ private void ProcessStandardParameters(ApiDescription operation, MethodViewModel
                     // Remove params that have no setter. 
                     // Honestly I'm clueless why this isn't default behavior, but OK.
                     !p.PropViewModel.HasSetter
-
-                    // Remove the string "DataSource" parameter that is redundant with our data source model binding functionality.
-                    || (p.PropViewModel.Name == nameof(IDataSourceParameters.DataSource) && p.OperationParam.Type == typeof(string))
                 ))
                 {
                     parameters.Remove(noSetterProp.OperationParam);
                 }
             }
+
+            foreach (var paramVm in method.Parameters.Where(p => p.Type.IsA(typeof(IDataSource<>))))
+            {
+                var declaredFor =
+                    paramVm.GetAttributeValue<DeclaredForAttribute>(a => a.DeclaredFor)
+                    ?? paramVm.Type.GenericArgumentsFor(typeof(IDataSource<>))!.Single();
+
+                var dataSources = declaredFor.ClassViewModel!.ClientDataSources(reflectionRepository);
+
+                foreach (var dataSource in dataSources)
+                {
+                    foreach (var dsParam in dataSource.DataSourceParameters)
+                    {
+                        operation.ParameterDescriptions.Add(new ApiParameterDescription()
+                        {
+                            Source = BindingSource.Query,
+                            Name = $"{paramVm.Name}.{dsParam.Name}",
+                            IsRequired = false,
+                            Type = dsParam.Type.TypeInfo,
+                            ModelMetadata = operation.ParameterDescriptions.First().ModelMetadata.GetMetadataForProperty(dataSource.Type.TypeInfo, dsParam.Name)
+                        });
+                    }
+                }
+            }
         }
     }
 }