@team-supercharge/oasg 18.1.0 → 18.2.0

package/README.md

@@ -1277,19 +1277,31 @@ with **System.Text.Json**, targeting **.NET 10** and marked
 > implements each `I{ApiName}` and calls `app.MapAll{PackageName}Endpoints()`; the
 > abstract MVC controllers are suppressed.
 >
-> The model/DTO layer is also AOT-clean: each model emits a source-generated
-> `JsonSerializerContext` and its `ToJson()` serializes through it (no Newtonsoft,
-> no reflection `JsonSerializer`). Minimal APIs are Native-AOT compatible (unlike
-> MVC), so combined with the source-generated models this server can be
-> Native-AOT published.
+> The package builds AOT-clean: it sets `<EnableRequestDelegateGenerator>` so the
+> minimal-API `Map*()` calls are statically generated (no reflection-based request
+> delegates), each model emits a source-generated `JsonSerializerContext` used by
+> its `ToJson()` (no Newtonsoft, no reflection `JsonSerializer`), and there is no
+> reflection-based enum converter. Building the package under the AOT analyzer
+> (`<IsAotCompatible>`) raises no IL2026/IL3050 warnings.
 >
-> The host must also register the package's JSON options so enums deserialize by
-> their `[EnumMember]` wire value (e.g. `"available"`), which the minimal-API STJ
-> pipeline does not do out of the box:
+> Enums (de)serialize by their wire value (e.g. `"available"`): each generated enum
+> carries `[JsonConverter(typeof(JsonStringEnumConverter<T>))]` with per-member
+> `[JsonStringEnumMemberName]`, which the source generator honours.
+>
+> **JSON registration.** The package generates a `{PackageName}JsonSerializerContext`
+> (a source-generated `JsonSerializerContext` over every model, request/response type
+> and inline enum) plus an `Add{PackageName}JsonOptions()` extension that registers it
+> on the minimal-API JSON resolver chain. Call it in Program.cs:
 >
 > ```csharp
 > builder.Services.Add{PackageName}JsonOptions();
 > ```
+>
+> This is **required when the host is published with Native AOT** (`PublishAot=true`),
+> because AOT removes the reflection JSON fallback and the endpoints must resolve every
+> DTO through source generation. For a reflection-based (JIT) host it is harmless (the
+> reflection resolver already covers everything), but registering it still gives faster,
+> allocation-free metadata, so calling it unconditionally is recommended.
 
 ##### `withWolverineImplementation`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-supercharge/oasg",
-  "version": "18.1.0",
+  "version": "18.2.0",
   "description": "Node-based tool to lint OpenAPI documents and generate clients, servers and documentation from them",
   "author": "Supercharge",
   "license": "MIT",

package/targets/dotnet-webapi-system-text-json/README.md

@@ -31,6 +31,12 @@ Everything lives in a single `EndpointRouteBuilderExtensions.cs`:
 - **`ConfigureWolverineMessaging(this WolverineOptions, string localQueueName = "MyApi")`** —
   routes every request type in the assembly to a local queue.
 
+A separate `ServiceCollectionExtensions.cs` holds a source-generated
+`{PackageName}JsonSerializerContext` (covering every model, request/response type
+and inline enum) and an **`Add{PackageName}JsonOptions(this IServiceCollection)`**
+extension that registers it on the minimal-API JSON resolver chain — call it in
+Program.cs (required when publishing the host with Native AOT; harmless otherwise).
+
 The `WolverineFx` package reference is added automatically.
 
 ---
@@ -61,6 +67,7 @@ using MyApi; // generated Map{ApiName}Endpoints / MapAllMyApiEndpoints / Configu
 
 var builder = WebApplication.CreateBuilder(args);
 builder.Services.AddHttpContextAccessor(); // see "Authentication" below
+builder.Services.AddMyApiJsonOptions();    // register the source-gen JSON context (required for Native AOT)
 
 builder.Host.UseWolverine(opts =>
 {

package/targets/dotnet-webapi-system-text-json/generate.sh

@@ -26,7 +26,7 @@ if [ -f "$endpointsFile" ]; then
   sed -i.bak 's/\.MapHttp/.Map/g' "$destFile" && rm -f "$destFile.bak"
 fi
 
-# Same for the JSON-options service-collection extension (SupportingFiles file).
+# Same for the JSON source-gen context / service-collection extension (SupportingFiles file).
 serviceExtFile="out/$targetId/ServiceCollectionExtensions.cs"
 if [ -f "$serviceExtFile" ]; then
   mv "$serviceExtFile" "out/$targetId/src/$packageName/ServiceCollectionExtensions.cs"

package/targets/dotnet-webapi-system-text-json/generator-config.json

@@ -12,7 +12,7 @@
     "nullableReferenceTypes": true,
     "operationResultTask": true,
     "useNewtonsoft": false,
-    "enumNameSuffix": "",
+    "enumNameSuffix": "Enum",
     "enumValueSuffix": "",
     "wolverineVersion": "6.10.0"
   },

package/targets/dotnet-webapi-system-text-json/templates/Project.csproj.mustache

@@ -5,6 +5,11 @@
         <Authors>{{packageAuthors}}</Authors>
         <TargetFramework>net10.0</TargetFramework>
         <IsAotCompatible>true</IsAotCompatible>
+        <!-- Statically generate the minimal-API request delegates (interceptors) so the
+             Map*() calls are trim-/AOT-safe instead of reflection-based at runtime.
+             Without this the [RequiresDynamicCode]/[RequiresUnreferencedCode] Map*
+             overloads raise IL3050/IL2026 under the AOT analyzer enabled above. -->
+        <EnableRequestDelegateGenerator>true</EnableRequestDelegateGenerator>
         <GenerateDocumentationFile>true</GenerateDocumentationFile>
         <PreserveCompilationContext>true</PreserveCompilationContext>
         <Version>{{packageVersion}}</Version>
@@ -38,9 +43,6 @@
         {{^useFrameworkReference}}
         <PackageReference Include="Microsoft.AspNetCore.App" />
         {{/useFrameworkReference}}
-        {{^useSeparateModelProject}}
-        <PackageReference Include="Microsoft.Extensions.Configuration.Json" {{#usePackageVersions}}Version="{{aspnetCoreVersion}}.0" {{/usePackageVersions}}/>
-        {{/useSeparateModelProject}}
         {{#useSwashbuckle}}
         <PackageReference Include="Microsoft.VisualStudio.Azure.Containers.Tools.Targets" {{#usePackageVersions}}Version="1.10.8" {{/usePackageVersions}}/>
         {{#useNewtonsoft}}
@@ -57,7 +59,6 @@
         <PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" {{#usePackageVersions}}Version="{{newtonsoftVersion}}" {{/usePackageVersions}}/>
         {{/useNewtonsoft}}
         {{/useSwashbuckle}}
-        <PackageReference Include="JsonSubTypes" {{#usePackageVersions}}Version="1.8.0" {{/usePackageVersions}}/>
     </ItemGroup>
     <ItemGroup>
         <!--<DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="{{aspnetCoreVersion}}.0" />-->

package/targets/dotnet-webapi-system-text-json/templates/enumClass.mustache

@@ -0,0 +1,24 @@
+
+        /// <summary>
+        /// {{^description}}Gets or Sets {{{name}}}{{/description}}{{{description}}}
+        /// </summary>
+        {{#description}}
+        /// <value>{{{.}}}</value>
+        {{/description}}
+        {{! AOT-safe enum (de)serialization: the source-generated, generic }}
+        {{! JsonStringEnumConverter<T> (no runtime MakeGenericType/Activator) plus the }}
+        {{! per-member JsonStringEnumMemberName below, which maps each value to its wire }}
+        {{! form. The attribute travels with the type, so enums round-trip as strings }}
+        {{! for reflection-based (JIT) hosts and source-generated (AOT) hosts alike. }}
+        [JsonConverter(typeof(JsonStringEnumConverter<{{datatypeWithEnum}}{{^datatypeWithEnum}}{{classname}}{{/datatypeWithEnum}}>))]
+        public enum {{datatypeWithEnum}}{{^datatypeWithEnum}}{{classname}}{{/datatypeWithEnum}}
+        {
+            {{#allowableValues}}{{#enumVars}}
+            /// <summary>
+            /// Enum {{name}} for {{{value}}}
+            /// </summary>
+            {{#isString}}[EnumMember(Value = "{{{value}}}")]
+            [JsonStringEnumMemberName("{{{value}}}")]{{/isString}}
+            {{name}}{{^isString}} = {{{value}}}{{/isString}}{{#isString}} = {{-index}}{{/isString}}{{^-last}},
+            {{/-last}}{{/enumVars}}{{/allowableValues}}
+        }

package/targets/dotnet-webapi-system-text-json/templates/minimalEndpoints.mustache

@@ -1,5 +1,6 @@
 // <auto-generated/>
 #nullable enable
+using System;
 using System.Collections.Generic;
 using System.Threading;
 using System.Threading.Tasks;
@@ -25,6 +26,7 @@ namespace {{packageName}}
     {
 {{#operations}}
 {{#operation}}
+        /// <summary>Application logic for the {{operationId}} operation.</summary>
         Task<IResult> {{operationId}}({{#allParams}}{{>paramType}} {{paramName}}, {{/allParams}}CancellationToken cancellationToken);
 {{/operation}}
 {{/operations}}
@@ -76,7 +78,7 @@ namespace {{packageName}}
 {{/apis}}
 {{/apiInfo}}
         /// <summary>Maps the endpoints of every generated API.</summary>
-        public static IEndpointRouteBuilder MapAll{{packageName}}Endpoints(this IEndpointRouteBuilder endpoints)
+        public static IEndpointRouteBuilder MapAll{{#lambda.pascalcase}}{{packageName}}{{/lambda.pascalcase}}Endpoints(this IEndpointRouteBuilder endpoints)
         {
 {{#apiInfo}}
 {{#apis}}

package/targets/dotnet-webapi-system-text-json/templates/model.mustache

@@ -23,7 +23,6 @@ using Swashbuckle.AspNetCore.Annotations;
 {{/discriminator}}
 {{/model}}
 {{/models}}
-using {{packageName}}.Converters;
 
 {{#models}}
 {{#model}}

package/targets/dotnet-webapi-system-text-json/templates/serviceCollectionExtensions.mustache

@@ -1,66 +1,90 @@
 // <auto-generated/>
+#nullable enable
 using System;
 using System.Collections.Generic;
-using System.Reflection;
-using System.Runtime.Serialization;
-using System.Text.Json;
 using System.Text.Json.Serialization;
-using Microsoft.AspNetCore.Http.Json;
 using Microsoft.Extensions.DependencyInjection;
+using {{packageName}}.Models;
 
 namespace {{packageName}}
 {
     /// <summary>
-    /// Registers the System.Text.Json options required by this generated package.
-    /// Call <c>builder.Services.Add{{packageName}}JsonOptions()</c> in Program.cs.
+    /// System.Text.Json source-generation context covering every type this package
+    /// (de)serializes through its minimal-API endpoints: each generated model, each
+    /// operation request/response type, and each inline enum. Registering it (see
+    /// <see cref="{{#lambda.pascalcase}}{{packageName}}{{/lambda.pascalcase}}ServiceCollectionExtensions" />)
+    /// lets the endpoints resolve JSON metadata via source generation, which is what
+    /// makes the package safe to trim and to publish with Native AOT — the pipeline
+    /// never falls back to reflection.
     /// </summary>
-    public static class {{packageName}}ServiceCollectionExtensions
+    /// <remarks>
+    /// Duplicate <c>[JsonSerializable]</c> entries are coalesced by the generator, so
+    /// request/response types that are also models are harmless. Inline enums are
+    /// registered with an explicit <c>TypeInfoPropertyName</c> because two models can
+    /// declare equally-named nested enums (e.g. <c>Order.StatusEnum</c> and
+    /// <c>Pet.StatusEnum</c>), which would otherwise collide under SYSLIB1031.
+    /// </remarks>
+    [JsonSerializable(typeof(string))]
+{{#models}}
+{{#model}}
+    [JsonSerializable(typeof({{classname}}))]
+{{#vars}}
+{{#isEnum}}
+{{^complexType}}
+    [JsonSerializable(typeof({{classname}}.{{datatypeWithEnum}}), TypeInfoPropertyName = "{{classname}}{{datatypeWithEnum}}")]
+{{/complexType}}
+{{/isEnum}}
+{{#items.isEnum}}
+{{#items}}
+{{^complexType}}
+    [JsonSerializable(typeof({{classname}}.{{datatypeWithEnum}}), TypeInfoPropertyName = "{{classname}}{{datatypeWithEnum}}")]
+{{/complexType}}
+{{/items}}
+{{/items.isEnum}}
+{{/vars}}
+{{/model}}
+{{/models}}
+{{#apiInfo}}
+{{#apis}}
+{{#operations}}
+{{#operation}}
+{{^isResponseFile}}
+{{#returnType}}
+    [JsonSerializable(typeof({{{returnType}}}))]
+{{/returnType}}
+{{/isResponseFile}}
+{{#bodyParam}}
+{{^isBinary}}
+    [JsonSerializable(typeof({{#isArray}}List<{{{items.dataType}}}>{{/isArray}}{{^isArray}}{{{baseType}}}{{/isArray}}))]
+{{/isBinary}}
+{{/bodyParam}}
+{{/operation}}
+{{/operations}}
+{{/apis}}
+{{/apiInfo}}
+    public partial class {{#lambda.pascalcase}}{{packageName}}{{/lambda.pascalcase}}JsonSerializerContext : JsonSerializerContext
     {
-        public static IServiceCollection Add{{packageName}}JsonOptions(this IServiceCollection services)
-        {
-            services.Configure<JsonOptions>(opts =>
-                opts.SerializerOptions.Converters.Add(new EnumMemberJsonConverterFactory()));
-            return services;
-        }
     }
 
     /// <summary>
-    /// Converts enums using their <see cref="EnumMemberAttribute" /> wire values (falling back to
-    /// the member name), so JSON like <c>"available"</c> round-trips to <c>StatusEnum.Available</c>.
+    /// Registers the System.Text.Json source-generation context for this generated
+    /// package. Call <c>builder.Services.Add{{#lambda.pascalcase}}{{packageName}}{{/lambda.pascalcase}}JsonOptions()</c>
+    /// in Program.cs so the minimal-API endpoints resolve JSON metadata via source
+    /// generation — required when the host is published with Native AOT, harmless
+    /// (a no-op the reflection resolver already covers) for a JIT host.
     /// </summary>
-    internal sealed class EnumMemberJsonConverterFactory : JsonConverterFactory
+    public static class {{#lambda.pascalcase}}{{packageName}}{{/lambda.pascalcase}}ServiceCollectionExtensions
     {
-        public override bool CanConvert(Type typeToConvert) => typeToConvert.IsEnum;
-
-        public override JsonConverter? CreateConverter(Type typeToConvert, JsonSerializerOptions options) =>
-            (JsonConverter?)Activator.CreateInstance(
-                typeof(EnumMemberJsonConverter<>).MakeGenericType(typeToConvert));
-    }
-
-    internal sealed class EnumMemberJsonConverter<T> : JsonConverter<T> where T : struct, Enum
-    {
-        private static readonly Dictionary<string, T> _read;
-        private static readonly Dictionary<T, string> _write;
-
-        static EnumMemberJsonConverter()
+        /// <summary>
+        /// Inserts <see cref="{{#lambda.pascalcase}}{{packageName}}{{/lambda.pascalcase}}JsonSerializerContext" />
+        /// at the front of the minimal-API JSON type-info resolver chain.
+        /// </summary>
+        public static IServiceCollection Add{{#lambda.pascalcase}}{{packageName}}{{/lambda.pascalcase}}JsonOptions(this IServiceCollection services)
         {
-            _read = new Dictionary<string, T>(StringComparer.OrdinalIgnoreCase);
-            _write = new Dictionary<T, string>();
-            foreach (var field in typeof(T).GetFields(BindingFlags.Public | BindingFlags.Static))
-            {
-                var wireValue = field.GetCustomAttribute<EnumMemberAttribute>()?.Value ?? field.Name;
-                var enumValue = (T)field.GetValue(null)!;
-                _read[wireValue] = enumValue;
-                _write[enumValue] = wireValue;
-            }
+            services.ConfigureHttpJsonOptions(options =>
+                options.SerializerOptions.TypeInfoResolverChain.Insert(
+                    0, {{#lambda.pascalcase}}{{packageName}}{{/lambda.pascalcase}}JsonSerializerContext.Default));
+            return services;
         }
-
-        public override T Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) =>
-            _read.TryGetValue(reader.GetString() ?? string.Empty, out var value)
-                ? value
-                : throw new JsonException($"Unknown value '{reader.GetString()}' for {typeof(T).Name}");
-
-        public override void Write(Utf8JsonWriter writer, T value, JsonSerializerOptions options) =>
-            writer.WriteStringValue(_write.TryGetValue(value, out var s) ? s : value.ToString());
     }
 }

package/targets/dotnet-webapi-system-text-json/templates/typeConverter.mustache

@@ -0,0 +1,11 @@
+// <auto-generated/>
+//
+// Intentionally empty for the System.Text.Json / Native-AOT target.
+//
+// The default aspnetcore template emits an MVC `CustomEnumConverter<T>`
+// (a TypeConverter whose body calls the reflection-based
+// JsonSerializer.Deserialize<T>, which raises IL2026/IL3050 under the AOT
+// analyzer). This target suppresses MVC controllers and (de)serializes enums
+// via [JsonConverter(typeof(JsonStringEnumConverter<T>))] + [JsonStringEnumMemberName]
+// on each generated enum, so the converter is unused — and is omitted here to
+// keep the package AOT-clean.