chore: enable Swagger UI

nmshd · Feb 27, 2025 · 8fba7ed · 8fba7ed
1 parent f8dd7e9
commit 8fba7ed
Show file tree

Hide file tree

Showing 4 changed files with 76 additions and 10 deletions.
diff --git a/Applications/ConsumerApi/src/ConsumerApi.csproj b/Applications/ConsumerApi/src/ConsumerApi.csproj
@@ -24,6 +24,7 @@
         <PackageReference Include="Serilog.Formatting.Compact" Version="3.0.0" />
         <PackageReference Include="Serilog.Sinks.Http" Version="9.1.0" />
         <PackageReference Include="Serilog.Sinks.Seq" Version="9.0.0" />
+        <PackageReference Include="Swashbuckle.AspNetCore" Version="7.2.0" />
     </ItemGroup>
 
     <ItemGroup>

diff --git a/Applications/ConsumerApi/src/Program.cs b/Applications/ConsumerApi/src/Program.cs
@@ -35,6 +35,7 @@
 using Microsoft.AspNetCore.HttpOverrides;
 using Microsoft.Extensions.Options;
 using Microsoft.IdentityModel.Logging;
+using Microsoft.OpenApi.Models;
 using Serilog;
 using Serilog.Enrichers.Sensitive;
 using Serilog.Exceptions;
@@ -130,6 +131,67 @@ static WebApplication CreateApp(string[] args)
 
 static void ConfigureServices(IServiceCollection services, IConfiguration configuration, IHostEnvironment environment)
 {
+    services.AddEndpointsApiExplorer();
+
+    services.AddSwaggerGen(c =>
+    {
+        c.CustomSchemaIds(t =>
+        {
+            static string GetReadableName(Type type)
+            {
+                if (!type.IsGenericType)
+                {
+                    return type.Name
+                        .Replace("DTO", string.Empty)
+                        .Replace("Command", "Request")
+                        .Replace("Query", "Request");
+                }
+
+                var typeName = type.Name
+                    .Replace("HttpResponseEnvelopeResult", "ResponseWrapper")
+                    .Replace("PagedHttpResponseEnvelopeResult", "PagedResponseWrapper");
+                var name = $"{typeName[..typeName.IndexOf('`')]}_{string.Join("_", type.GetGenericArguments().Select(GetReadableName))}";
+                return name;
+            }
+
+            return GetReadableName(t);
+        });
+
+        c.AddServer(new OpenApiServer { Url = "https://nmshd-bkb.demo.meinbildungsraum.de" });
+        c.AddServer(new OpenApiServer { Url = "https://nmshd-bkb.meinbildungsraum.de" });
+        c.AddServer(new OpenApiServer { Url = "https://pilot.enmeshed.eu" });
+
+        c.AddSecurityDefinition(
+            "oauth2",
+            new OpenApiSecurityScheme
+            {
+                Type = SecuritySchemeType.OAuth2,
+                Flows = new OpenApiOAuthFlows
+                {
+                    Password = new OpenApiOAuthFlow
+                    {
+                        TokenUrl = new Uri("/connect/token", UriKind.Relative)
+                    }
+                }
+            });
+
+        c.AddSecurityRequirement(
+            new OpenApiSecurityRequirement
+            {
+                {
+                    new OpenApiSecurityScheme
+                    {
+                        Reference = new OpenApiReference
+                        {
+                            Id = "oauth2", //The name of the previously defined security scheme.
+                            Type = ReferenceType.SecurityScheme
+                        }
+                    },
+                    new List<string>()
+                }
+            });
+    });
+
     services.ConfigureAndValidate<BackboneConfiguration>(configuration.Bind);
 
 #pragma warning disable ASP0000 // We retrieve the BackboneConfiguration via IOptions here so that it is validated
@@ -181,6 +243,9 @@ static void ConfigureServices(IServiceCollection services, IConfiguration config
 
 static void Configure(WebApplication app)
 {
+    app.UseSwagger();
+    app.UseSwaggerUI();
+
     app.UseSerilogRequestLogging(opts =>
     {
         opts.EnrichDiagnosticContext = LogHelper.EnrichFromRequest;

diff --git a/BuildingBlocks/src/BuildingBlocks.API/HttpResponseEnvelope.cs b/BuildingBlocks/src/BuildingBlocks.API/HttpResponseEnvelope.cs
@@ -30,20 +30,20 @@ public HttpResponseEnvelopeResult(T result)
 
 public class PagedHttpResponseEnvelope<T> : HttpResponseEnvelopeResult<IEnumerable<T>>
 {
-    public PagedHttpResponseEnvelope(IEnumerable<T> result, PaginationData paginationData) : base(result)
+    public PagedHttpResponseEnvelope(IEnumerable<T> result, PagedHttpResponseEnvelopePaginationData paginationData) : base(result)
     {
         Pagination = paginationData;
     }
 
-    public PaginationData Pagination { get; set; }
+    public PagedHttpResponseEnvelopePaginationData Pagination { get; set; }
+}
 
-    public class PaginationData
-    {
-        public int PageNumber { get; set; }
-        public int? PageSize { get; set; }
-        public int TotalPages { get; set; }
-        public int TotalRecords { get; set; }
-    }
+public class PagedHttpResponseEnvelopePaginationData
+{
+    public int PageNumber { get; set; }
+    public int? PageSize { get; set; }
+    public int TotalPages { get; set; }
+    public int TotalRecords { get; set; }
 }
 
 public class HttpResponseEnvelopeError : HttpResponseEnvelope

diff --git a/BuildingBlocks/src/BuildingBlocks.API/Mvc/ApiControllerBase.cs b/BuildingBlocks/src/BuildingBlocks.API/Mvc/ApiControllerBase.cs
@@ -68,7 +68,7 @@ public OkObjectResult Paged<T>(IEnumerable<T> pagedData, PaginationData paginati
     {
         if (paginationData.TotalPages <= 1) return Ok(pagedData);
 
-        var response = new PagedHttpResponseEnvelope<T>(pagedData, new PagedHttpResponseEnvelope<T>.PaginationData
+        var response = new PagedHttpResponseEnvelope<T>(pagedData, new PagedHttpResponseEnvelopePaginationData
         {
             TotalRecords = paginationData.TotalRecords,
             PageNumber = paginationData.PageNumber,