From 2fcea78574484b8b36ec04e1446040622568240b Mon Sep 17 00:00:00 2001
From: TekH <h.tek@digitaldata.works>
Date: Tue, 3 Feb 2026 11:13:53 +0100
Subject: [PATCH] Add Swagger doc filter for /api/auth proxy login endpoint

Introduced AuthProxyDocumentFilter to programmatically document the POST /api/auth proxy login endpoint in Swagger. The filter defines request body schemas, example values, query parameter, and response codes. Registered the filter in Program.cs for OpenAPI generation.
---
 .../Documentation/AuthProxyDocumentFilter.cs  | 70 +++++++++++++++++++
 EnvelopeGenerator.API/Program.cs              |  2 +
 2 files changed, 72 insertions(+)
 create mode 100644 EnvelopeGenerator.API/Documentation/AuthProxyDocumentFilter.cs

diff --git a/EnvelopeGenerator.API/Documentation/AuthProxyDocumentFilter.cs b/EnvelopeGenerator.API/Documentation/AuthProxyDocumentFilter.cs
new file mode 100644
index 00000000..d4ae7480
--- /dev/null
+++ b/EnvelopeGenerator.API/Documentation/AuthProxyDocumentFilter.cs
@@ -0,0 +1,70 @@
+using EnvelopeGenerator.API.Models;
+using Microsoft.OpenApi.Any;
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.SwaggerGen;
+
+namespace EnvelopeGenerator.API.Documentation;
+
+/// <summary>
+/// 
+/// </summary>
+public sealed class AuthProxyDocumentFilter : IDocumentFilter
+{
+    /// <summary>
+    /// 
+    /// </summary>
+    /// <param name="swaggerDoc"></param>
+    /// <param name="context"></param>
+    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
+    {
+        const string path = "/api/auth";
+
+        var loginSchema = context.SchemaGenerator.GenerateSchema(typeof(Login), context.SchemaRepository);
+        var loginExample = new OpenApiObject
+        {
+            ["password"] = new OpenApiString(""),
+            ["username"] = new OpenApiString("")
+        };
+
+        var operation = new OpenApiOperation
+        {
+            Summary = "Proxy login (auth-hub)",
+            Description = "Proxies the request to the auth service. Add query parameter `cookie=true|false`.",
+            Tags = [new() { Name = "Auth" }],
+            Parameters =
+            {
+                new OpenApiParameter
+                {
+                    Name = "cookie",
+                    In = ParameterLocation.Query,
+                    Required = false,
+                    Schema = new OpenApiSchema { Type = "boolean", Default = new OpenApiBoolean(true) },
+                    Example = new OpenApiBoolean(true),
+                    Description = "If true, auth service sets the auth cookie."
+                }
+            },
+            RequestBody = new OpenApiRequestBody
+            {
+                Required = true,
+                Content =
+                {
+                    ["application/json"] = new OpenApiMediaType { Schema = loginSchema, Example = loginExample },
+                    ["multipart/form-data"] = new OpenApiMediaType { Schema = loginSchema, Example = loginExample }
+                }
+            },
+            Responses =
+            {
+                ["200"] = new OpenApiResponse { Description = "OK (proxied response)" },
+                ["401"] = new OpenApiResponse { Description = "Unauthorized" }
+            }
+        };
+
+        swaggerDoc.Paths[path] = new OpenApiPathItem
+        {
+            Operations =
+            {
+                [OperationType.Post] = operation
+            }
+        };
+    }
+}
\ No newline at end of file
diff --git a/EnvelopeGenerator.API/Program.cs b/EnvelopeGenerator.API/Program.cs
index cd63d65c..468e1d82 100644
--- a/EnvelopeGenerator.API/Program.cs
+++ b/EnvelopeGenerator.API/Program.cs
@@ -106,6 +106,8 @@ try
         {
             options.IncludeXmlComments(xmlFile);
         }
+
+        options.DocumentFilter<EnvelopeGenerator.API.Documentation.AuthProxyDocumentFilter>();
     });
     builder.Services.AddOpenApi();