Update Swagger support for .NET 10.0 and improve enum docs (#7377)

- Bump project version to 2.16.
- Add Swashbuckle.AspNetCore packages for .NET 10.0 builds.
- Refactor XEnumNamesSchemaFilter with conditional logic for .NET 10.0+ using new OpenAPI APIs.
- Update ServiceCollectionExtensions to use new schema types and mappings for .NET 10.0+.
- Preserve compatibility with earlier .NET versions.

Author: cleftheris

common.props

@@ -15,7 +15,7 @@
         <!-- https://github.com/dotnet/sourcelink -->
         <IncludeSymbols>true</IncludeSymbols>
         <SymbolPackageFormat>snupkg</SymbolPackageFormat>
-        <Version>2.15</Version>
+        <Version>2.16</Version>
 
         <IsTrimmable>false</IsTrimmable>
         <EnableTrimAnalyzer>false</EnableTrimAnalyzer>

src/server/Elsa.Server.Api/Elsa.Server.Api.csproj

@@ -26,6 +26,10 @@
         <PackageReference Include="System.Linq.Async" Version="6.0.1">
             <ExcludeAssets>compile</ExcludeAssets>
         </PackageReference>
+        <PackageReference Include="Swashbuckle.AspNetCore" Version="10.1.7" />
+        <PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="10.1.7" />
+        <PackageReference Include="Swashbuckle.AspNetCore.Filters" Version="10.0.1" />
+        <PackageReference Include="Swashbuckle.AspNetCore.SwaggerGen" Version="10.1.7" />
     </ItemGroup>
 
     <ItemGroup>

src/server/Elsa.Server.Api/Extensions/SchemaFilters/XEnumNamesSchemaFilter.cs

@@ -1,9 +1,14 @@
+#if NET10_0_OR_GREATER
+using Microsoft.OpenApi;
+using System.Text.Json.Nodes;
+using System.Collections.Generic;
+#else
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Models;
+#endif
 using Swashbuckle.AspNetCore.SwaggerGen;
 using System;
 using System.Linq;
-using System.Reflection;
 
 namespace Elsa.Server.Api.Extensions.SchemaFilters
 {
@@ -13,6 +18,64 @@ public class XEnumNamesSchemaFilter : ISchemaFilter
         private const string openapiGenerator = "x-enum-varnames";
 
 
+#if NET10_0_OR_GREATER
+        public void Apply(IOpenApiSchema schema, SchemaFilterContext context)
+        {
+            if (context.Type.IsEnum && schema is OpenApiSchema model)
+            {
+                AddGeneratorSupport(model, context, nswag);
+                AddGeneratorSupport(model, context, openapiGenerator);
+                AddSwaggerUiSupport(model, context);
+            }
+        }
+        private void AddGeneratorSupport(OpenApiSchema model, SchemaFilterContext context, string generatorType)
+        {
+            if (model.Extensions?.ContainsKey(generatorType) != true)
+            {
+                var names = Enum.GetNames(context.Type).Select(x => (JsonNode)x).ToList();
+                model.Extensions ??= new Dictionary<string, IOpenApiExtension>();
+                model.Extensions.Add(generatorType, new EnumNamesOpenApiExtension(names));
+            }
+        }
+
+        private void AddSwaggerUiSupport(OpenApiSchema model, SchemaFilterContext context)
+        {
+            model.Enum?.Clear();
+            model.Enum ??= [];
+            Enum.GetNames(context.Type)
+                .ToList()
+                .ForEach(n =>
+                {
+                    model.Enum.Add((JsonNode)n);
+                    model.Type = JsonSchemaType.String;
+                    model.Format = null;
+                });
+        }
+
+        internal class EnumNamesOpenApiExtension : IOpenApiExtension
+        {
+            public EnumNamesOpenApiExtension(List<JsonNode> enumDescriptions)
+            {
+                EnumDescriptions = enumDescriptions;
+            }
+
+            public List<JsonNode> EnumDescriptions { get; }
+
+            public void Write(IOpenApiWriter writer, OpenApiSpecVersion specVersion)
+            {
+                if (writer is null)
+                {
+                    throw new ArgumentNullException(nameof(writer));
+                }
+                writer.WriteStartArray();
+                foreach (var description in EnumDescriptions)
+                {
+                    writer.WriteAny(description);
+                }
+                writer.WriteEndArray();
+            }
+        }
+#else
         public void Apply(OpenApiSchema model, SchemaFilterContext context)
         {
             if (context.Type.IsEnum)
@@ -47,5 +110,7 @@ private void AddSwaggerUiSupport(OpenApiSchema model, SchemaFilterContext contex
                     model.Format = null;
                 });
         }
+#endif
+
     }
 }

src/server/Elsa.Server.Api/Extensions/ServiceCollectionExtensions.cs

@@ -7,9 +7,12 @@
 using Elsa.Server.Api.Mapping;
 using Elsa.Server.Api.Services;
 using Elsa.Server.Api.Swagger.Examples;
-using Microsoft.AspNetCore.Mvc;
+#if NET10_0_OR_GREATER
+using Microsoft.OpenApi;
+#else
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Models;
+#endif
 using Swashbuckle.AspNetCore.Filters;
 using Swashbuckle.AspNetCore.SwaggerGen;
 using System;
@@ -73,17 +76,29 @@ public static IServiceCollection AddElsaSwagger(this IServiceCollection services
                     //c.ExampleFilters(); I don't know why, this line will make swagger error
                     c.MapType<VersionOptions?>(() => new OpenApiSchema
                     {
+#if NET10_0_OR_GREATER
+                        Type = JsonSchemaType.String | JsonSchemaType.Null,
+                        Example = "Latest",
+                        Description = "Any of Latest, Published, Draft, LatestOrPublished or a specific version number.",
+                        Default = "Latest"
+#else
                         Type = PrimitiveType.String.ToString().ToLower(),
                         Example = new OpenApiString("Latest"),
                         Description = "Any of Latest, Published, Draft, LatestOrPublished or a specific version number.",
                         Nullable = true,
                         Default = new OpenApiString("Latest")
+#endif
                     });
 
                     c.MapType<Type>(() => new OpenApiSchema
                     {
+#if NET10_0_OR_GREATER
+                        Type = JsonSchemaType.String,
+                        Example = "System.String, mscorlib"
+#else
                         Type = PrimitiveType.String.ToString().ToLower(),
                         Example = new OpenApiString("System.String, mscorlib")
+#endif
                     });
 
                     //Allow enums to be displayed