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.

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
+            }
+        };
+    }
+}

EnvelopeGenerator.API/Program.cs

@@ -106,6 +106,8 @@ try
         {
             options.IncludeXmlComments(xmlFile);
         }
+
+        options.DocumentFilter<EnvelopeGenerator.API.Documentation.AuthProxyDocumentFilter>();
     });
     builder.Services.AddOpenApi();