fix: endpoints invisible to OpenAPI/Swagger (#25)

Three-part fix for endpoints being invisible in OpenAPI documents:

1. Wrapper returns typed `Task<Results<...>>` instead of plain `Task`,
   breaking the `RequestDelegate` signature match so `MapGet` picks the
   `Delegate` overload and `RequestDelegateFactory` processes it.

2. `(Delegate)` cast on all endpoint registrations as a safety net,
   explicitly forcing the `Delegate` overload regardless of signature.

3. Always emit explicit `ProducesResponseTypeMetadata` for every response
   type, giving the OpenAPI document generator full response schema info.

Additionally:
- Add OpenAPI parameter extraction (route, query, header) via operation
  transformer for `AddErrorOrOpenApi()` consumers
- Update README and CLAUDE.md examples from int to Guid
- Bump version to 3.5.0

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ANcpLua

CLAUDE.md

@@ -31,18 +31,18 @@ Convert `ErrorOr<T>` handlers into fully-wired ASP.NET endpoints:
 
 ```
 User writes:                         Generator produces:
-[Get("/todos/{id}")]                 app.MapGet("/todos/{id}", Invoke_Ep1)
-ErrorOr<Todo> GetById(int id)   ->       .WithName("TodoApi_GetById")
+[Get("/todos/{id:guid}")]             app.MapGet("/todos/{id:guid}", (Delegate)Invoke_Ep1)
+ErrorOr<Todo> GetById(Guid id)  ->       .WithName("TodoApi_GetById")
+                                         .WithMetadata(new ProducesResponseTypeMetadata(...))
                                          .RequireAuthorization("Admin")
                                          ;
 
-                                     static async Task Invoke_Ep1(HttpContext ctx)
+                                     static async Task<Results<Ok<Todo>, ...>> Invoke_Ep1(HttpContext ctx)
                                      {
-                                         var __result = await Invoke_Ep1_Core(ctx);
-                                         await __result.ExecuteAsync(ctx);
+                                         return await Invoke_Ep1_Core(ctx);
                                      }
 
-                                     static Task<IResult> Invoke_Ep1_Core(...)
+                                     static Task<Results<Ok<Todo>, ...>> Invoke_Ep1_Core(...)
                                      {
                                          var result = TodoApi.GetById(id);
                                          if (result.IsError) return ToProblem(result.Errors);
@@ -71,24 +71,24 @@ return result.Match(
 
 ### AOT Wrapper Pattern
 
-Two-method pattern ensures Native AOT compatibility:
+Two-method pattern ensures Native AOT compatibility and OpenAPI visibility:
 
 ```csharp
-// Wrapper - matches RequestDelegate (HttpContext -> Task)
-private static async Task Invoke_Ep1(HttpContext ctx)
+// Wrapper - returns typed Results<...> for OpenAPI metadata
+// MapGet uses (Delegate)Invoke_Ep1 to force the Delegate overload
+private static async Task<Results<Ok<Todo>, NotFound<PD>>> Invoke_Ep1(HttpContext ctx)
 {
-    var __result = await Invoke_Ep1_Core(ctx);
-    await __result.ExecuteAsync(ctx);
+    return await Invoke_Ep1_Core(ctx);
 }
 
-// Core - returns typed Results<...> for OpenAPI
+// Core - returns typed Results<...> with handler logic
 private static Task<Results<Ok<Todo>, NotFound<ProblemDetails>>> Invoke_Ep1_Core(HttpContext ctx)
 {
     // ... handler logic using minimal interface
 }
 ```
 
-**Why**: `(Delegate)` cast forces reflection; `Task<Results<...>>` cannot have `[JsonSerializable]`.
+**Why**: Without `(Delegate)` cast, `Func<HttpContext, Task<T>>` matches `RequestDelegate` — endpoints become invisible to OpenAPI. The cast forces `RequestDelegateFactory` to process the delegate, enabling typed return inspection.
 
 ### Middleware Emission
 

README.md

@@ -143,16 +143,16 @@ using ErrorOr;
 
 public static class TodoApi
 {
-    [Get("/todos/{id}")]
-    public static ErrorOr<Todo> GetById(int id, ITodoService svc)
+    [Get("/todos/{id:guid}")]
+    public static ErrorOr<Todo> GetById(Guid id, ITodoService svc)
         => svc.GetById(id).OrNotFound($"Todo {id} not found");
 
     [Post("/todos")]
     public static ErrorOr<Todo> Create(CreateTodoRequest req, ITodoService svc)
         => svc.Create(req);  // 201 Created
 
-    [Delete("/todos/{id}")]
-    public static ErrorOr<Deleted> Delete(int id, ITodoService svc)
+    [Delete("/todos/{id:guid}")]
+    public static ErrorOr<Deleted> Delete(Guid id, ITodoService svc)
         => svc.Delete(id) ? Result.Deleted : Error.NotFound();
 }
 ```
@@ -244,11 +244,11 @@ public interface ITodoService
 {
     [ReturnsError(ErrorType.NotFound, "Todo.NotFound")]
     [ReturnsError(ErrorType.Validation, "Todo.Invalid")]
-    ErrorOr<Todo> GetById(int id);
+    ErrorOr<Todo> GetById(Guid id);
 }
 
-[Get("/todos/{id}")]
-public static ErrorOr<Todo> GetById(int id, ITodoService svc) =>
+[Get("/todos/{id:guid}")]
+public static ErrorOr<Todo> GetById(Guid id, ITodoService svc) =>
     svc.GetById(id);
 // Generates: Results<Ok<Todo>, NotFound<ProblemDetails>, ValidationProblem>
 ```
@@ -267,9 +267,9 @@ public static ErrorOr<Todo> Create(
     ITodoService svc)         // -> Service (interface)
     => svc.Create(req);
 
-[Get("/todos/{id}")]
+[Get("/todos/{id:guid}")]
 public static ErrorOr<Todo> GetById(
-    int id,                   // -> Route (matches {id})
+    Guid id,                  // -> Route (matches {id})
     ITodoService svc)         // -> Service
     => svc.GetById(id).OrNotFound();
 ```

samples/ErrorOrX.Sample/Program.cs

@@ -1,7 +1,7 @@
 var builder = WebApplication.CreateSlimBuilder(args);
 
 builder.Services
-    .AddOpenApi()
+    .AddErrorOrOpenApi()
     .AddSingleton(TimeProvider.System)
     .AddScoped<ITodoService, TodoService>();
 
@@ -18,4 +18,5 @@
 // convention builder return (like ASP.NET Core's MapRazorComponents)
 app.MapErrorOrEndpoints();
 
+
 app.Run();

src/ErrorOrX.Generators/CLAUDE.md

@@ -7,8 +7,8 @@ Roslyn source generator and analyzers for ErrorOrX. Target: `netstandard2.0`.
 Converts `ErrorOr<T>` methods with route attributes into ASP.NET Core Minimal API endpoints:
 
 ```csharp
-[Get("/todos/{id}")]
-public static ErrorOr<Todo> GetById(int id) => ...
+[Get("/todos/{id:guid}")]
+public static ErrorOr<Todo> GetById(Guid id) => ...
 ```
 
 Outputs:
@@ -37,17 +37,17 @@ return result.Match(value => TypedResults.Ok(value), errors => ToProblem(errors)
 ### AOT Wrapper Pattern
 
 ```csharp
-// Wrapper - returns Task (no Delegate cast needed)
-private static async Task Invoke_Ep1(HttpContext ctx)
+// Wrapper - returns typed Results<...> for OpenAPI visibility
+// MapGet passes (Delegate)Invoke_Ep1 to force Delegate overload
+private static async Task<Results<Ok<T>, ...>> Invoke_Ep1(HttpContext ctx)
 {
-    var __result = await Invoke_Ep1_Core(ctx);
-    await __result.ExecuteAsync(ctx);
+    return await Invoke_Ep1_Core(ctx);
 }
 
 // Core - returns typed Results<...> for OpenAPI
 private static Task<IResult> Invoke_Ep1_Core(HttpContext ctx)
 {
-    int id = (int)ctx.Request.RouteValues["id"]!;
+    Guid id = Guid.Parse((string)ctx.Request.RouteValues["id"]!);
     var result = TodoApi.GetById(id);
     if (result.IsError) return Task.FromResult(ToProblem(result.Errors));
     return Task.FromResult(TypedResults.Ok(result.Value));

src/ErrorOrX.Generators/Core/ErrorOrEndpointGenerator.Emitter.cs

@@ -145,11 +145,13 @@ private static void EmitMapCall(StringBuilder code, in EndpointDescriptor ep, in
             $"            // {ep.HttpMethod} {ep.Pattern} -> {ep.HandlerContainingTypeFqn}.{ep.HandlerMethodName}");
         var mapMethod = Emit.MapMethod(ep.HttpMethod);
 
-        // Use typed Map* methods without Delegate cast for AOT compatibility
-        // Store builder for CompositeEndpointConventionBuilder
+        // Cast to Delegate to force the Delegate overload of MapGet/MapPost/etc.
+        // Without this cast, the compiler selects the RequestDelegate overload
+        // (since Func<HttpContext, Task<T>> is also Func<HttpContext, Task>),
+        // which bypasses RequestDelegateFactory and makes endpoints invisible to OpenAPI.
         code.AppendLine(mapMethod == "MapMethods"
-            ? $"            var __ep{index} = app.MapMethods(@\"{ep.Pattern}\", new[] {{ \"{ep.HttpMethod}\" }}, Invoke_Ep{index})"
-            : $"            var __ep{index} = app.{mapMethod}(@\"{ep.Pattern}\", Invoke_Ep{index})");
+            ? $"            var __ep{index} = app.MapMethods(@\"{ep.Pattern}\", new[] {{ \"{ep.HttpMethod}\" }}, (Delegate)Invoke_Ep{index})"
+            : $"            var __ep{index} = app.{mapMethod}(@\"{ep.Pattern}\", (Delegate)Invoke_Ep{index})");
 
         var (_, operationId) =
             EndpointNameHelper.GetEndpointIdentity(ep.HandlerContainingTypeFqn, ep.HandlerMethodName);
@@ -326,10 +328,10 @@ private static void EmitErrorHandling(
 
     private static void EmitWrapperMethod(StringBuilder code, in InvokerContext ctx)
     {
-        code.AppendLine($"        private static async Task {ctx.WrapperName}(HttpContext ctx)");
+        var returnType = ctx.UnionResult.ReturnTypeFqn;
+        code.AppendLine($"        private static async Task<{returnType}> {ctx.WrapperName}(HttpContext ctx)");
         code.AppendLine("        {");
-        code.AppendLine($"            var __result = await {ctx.CoreName}(ctx);");
-        code.AppendLine("            await __result.ExecuteAsync(ctx);");
+        code.AppendLine($"            return await {ctx.CoreName}(ctx);");
         code.AppendLine("        }");
         code.AppendLine();
     }

src/ErrorOrX.Generators/Emitters/EndpointMetadataEmitter.cs

@@ -92,25 +92,23 @@ private static void EmitProducesMetadata(StringBuilder code, in EndpointDescript
             ep.Middleware,
             ep.HasParameterValidation);
 
-        // Only emit explicit produces metadata when we can't use union types
-        // (Union types provide this metadata automatically)
-        if (!unionResult.CanUseUnion)
+        // Always emit explicit Produces metadata for OpenAPI visibility.
+        // The wrapper uses RequestDelegate signature (returns Task), so ASP.NET Core's
+        // RequestDelegateFactory never inspects the union return type for metadata.
+        // Success response
+        EmitProducesMetadataLine(code, indent, successInfo.StatusCode,
+            successInfo.HasBody ? ep.SuccessTypeFqn : null,
+            WellKnownTypes.Constants.ContentTypeJson);
+
+        // Error responses
+        foreach (var statusCode in unionResult.ExplicitProduceCodes.AsImmutableArray().Distinct()
+                     .OrderBy(static x => x))
         {
-            // Success response
-            EmitProducesMetadataLine(code, indent, successInfo.StatusCode,
-                successInfo.HasBody ? ep.SuccessTypeFqn : null,
-                WellKnownTypes.Constants.ContentTypeJson);
-
-            // Error responses
-            foreach (var statusCode in unionResult.ExplicitProduceCodes.AsImmutableArray().Distinct()
-                         .OrderBy(static x => x))
-            {
-                EmitProducesMetadataLine(code, indent, statusCode,
-                    statusCode == 400
-                        ? WellKnownTypes.Fqn.HttpValidationProblemDetails
-                        : WellKnownTypes.Fqn.ProblemDetails,
-                    WellKnownTypes.Constants.ContentTypeProblemJson);
-            }
+            EmitProducesMetadataLine(code, indent, statusCode,
+                statusCode == 400
+                    ? WellKnownTypes.Fqn.HttpValidationProblemDetails
+                    : WellKnownTypes.Fqn.ProblemDetails,
+                WellKnownTypes.Constants.ContentTypeProblemJson);
         }
     }
 

src/ErrorOrX.Generators/Emitters/GroupEmitter.cs

@@ -93,12 +93,13 @@ public static void EmitGroupedMapCall(
         // Use relative pattern (group prefix already handled by MapGroup)
         var relativePattern = GetRelativePattern(in ep);
 
-        // Emit the map call against the group variable
-        // Store builder for CompositeEndpointConventionBuilder
+        // Cast to Delegate to force the Delegate overload of MapGet/MapPost/etc.
+        // Without this cast, the compiler selects the RequestDelegate overload,
+        // which bypasses RequestDelegateFactory and makes endpoints invisible to OpenAPI.
         var mapMethod = GetMapMethod(ep.HttpMethod);
         code.Append(mapMethod == "MapMethods"
-            ? $"            var __ep{globalIndex} = {groupVarName}.MapMethods(@\"{relativePattern}\", new[] {{ \"{ep.HttpMethod}\" }}, Invoke_Ep{globalIndex})"
-            : $"            var __ep{globalIndex} = {groupVarName}.{mapMethod}(@\"{relativePattern}\", Invoke_Ep{globalIndex})");
+            ? $"            var __ep{globalIndex} = {groupVarName}.MapMethods(@\"{relativePattern}\", new[] {{ \"{ep.HttpMethod}\" }}, (Delegate)Invoke_Ep{globalIndex})"
+            : $"            var __ep{globalIndex} = {groupVarName}.{mapMethod}(@\"{relativePattern}\", (Delegate)Invoke_Ep{globalIndex})");
 
         // Emit operation name
         code.AppendLine();

src/ErrorOrX.Generators/Models/EndpointModels.cs

@@ -439,6 +439,16 @@ internal readonly record struct JsonContextInfo(
     EquatableArray<string> SerializableTypes,
     bool HasCamelCasePolicy);
 
+/// <summary>
+///     Represents a parameter for OpenAPI documentation.
+/// </summary>
+internal readonly record struct OpenApiParameterInfo(
+    string Name,
+    string Location,
+    bool Required,
+    string SchemaType,
+    string? SchemaFormat);
+
 /// <summary>
 ///     Immutable endpoint info for OpenAPI generation.
 /// </summary>
@@ -449,7 +459,8 @@ internal readonly record struct OpenApiEndpointInfo(
     string? Description,
     string HttpMethod,
     string Pattern,
-    EquatableArray<(string ParamName, string Description)> ParameterDocs);
+    EquatableArray<(string ParamName, string Description)> ParameterDocs,
+    EquatableArray<OpenApiParameterInfo> Parameters);
 
 /// <summary>
 ///     Immutable type metadata for schema generation.