Add detailed Swagger configuration and options

Updated `appsettings.json` to include a comprehensive "swagger" section with configuration options such as `enabled`, `title`, `description`, `version`, `termsOfService`, `contactName`, `contactEmail`, `contactUrl`, `licenseName`, `licenseUrl`, `includeSecurity`, and a list of `servers`.

Extended `SwaggerOptions` class to include new properties: `Description`, `ContactName`, `ContactEmail`, `ContactUrl`, `LicenseName`, `LicenseUrl`, `TermsOfService`, and a list of `OpenApiServer` objects. Added an inner class `OpenApiServer` to represent server details.

Modified `AddSwaggerDocs` method in `Extensions.cs` to handle the new `SwaggerOptions` properties, including logic for security definitions, custom operation IDs, and server details. Added XML comments to the Swagger documentation.

Provided specific values for the "swagger" section in `appsettings.json` for different environments (local development, containerized, and production).

Author: giovanninocco

src/Genocs.Core.Demo.WebApi/appsettings.json

@@ -70,5 +70,17 @@
     "caller": "<<>>",
     "public": "<<>>",
     "private": "<<>>"
+  },
+  "swagger": {
+    "enabled": true,
+    "title": "Demo WebApi",
+    "description": "Demo WebApi",
+    "version": "v1",
+    "servers": [
+      {
+        "name": "Genocs",
+        "email": "[email protected]"
+      }
+    ]
   }
 }

src/Genocs.WebApi.Swagger/Docs/Configurations/SwaggerOptions.cs

@@ -7,7 +7,23 @@ public class SwaggerOptions
     public string? Name { get; set; }
     public string? Title { get; set; }
     public string? Version { get; set; }
+    public string? Description { get; set; }
     public string? RoutePrefix { get; set; }
+    public string? ContactName { get; set; }
+    public string? ContactEmail { get; set; }
+    public string? ContactUrl { get; set; }
+    public string? LicenseName { get; set; }
+    public string? LicenseUrl { get; set; }
+    public string? TermsOfService { get; set; }
     public bool IncludeSecurity { get; set; }
     public bool SerializeAsOpenApiV2 { get; set; }
-}
+    public List<OpenApiServer>? Servers { get; set; }
+
+    public class OpenApiServer
+    {
+
+        public string? Url { get; set; }
+        public string? Description { get; set; }
+    }
+}
+

src/Genocs.WebApi.Swagger/Docs/Extensions.cs

@@ -1,7 +1,9 @@
+using System.Reflection;
 using Genocs.Core.Builders;
 using Genocs.WebApi.Swagger.Docs.Builders;
 using Genocs.WebApi.Swagger.Docs.Configurations;
 using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Mvc.Controllers;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.OpenApi.Models;
 
@@ -19,38 +21,126 @@ public static IGenocsBuilder AddSwaggerDocs(this IGenocsBuilder builder, string
             sectionName = SectionName;
         }
 
-        var options = builder.GetOptions<SwaggerOptions>(sectionName);
-        return builder.AddSwaggerDocs(options);
+        SwaggerOptions settings = builder.GetOptions<SwaggerOptions>(sectionName);
+
+        if (settings is null)
+        {
+            return builder;
+        }
+
+        return builder.AddSwaggerDocs(settings);
     }
 
     public static IGenocsBuilder AddSwaggerDocs(this IGenocsBuilder builder, Func<ISwaggerOptionsBuilder, ISwaggerOptionsBuilder> buildOptions)
     {
-        var options = buildOptions(new SwaggerOptionsBuilder()).Build();
-        return builder.AddSwaggerDocs(options);
+        SwaggerOptions settings = buildOptions(new SwaggerOptionsBuilder()).Build();
+
+        if (settings is null)
+        {
+            return builder;
+        }
+
+        return builder.AddSwaggerDocs(settings);
     }
 
-    public static IGenocsBuilder AddSwaggerDocs(this IGenocsBuilder builder, SwaggerOptions options)
+    public static IGenocsBuilder AddSwaggerDocs(this IGenocsBuilder builder, SwaggerOptions settings)
     {
-        if (!options.Enabled || !builder.TryRegister(RegistryName))
+        if (!settings.Enabled || !builder.TryRegister(RegistryName))
         {
             return builder;
         }
 
-        builder.Services.AddSingleton(options);
+        // TODO: Double-check if this is necessary
+        builder.Services.AddSingleton(settings);
+
+        // Register the Swagger generator, defining 1 or more Swagger documents
         builder.Services.AddSwaggerGen(c =>
         {
             c.EnableAnnotations();
-            c.SwaggerDoc(options.Name, new OpenApiInfo { Title = options.Title, Version = options.Version });
-            if (options.IncludeSecurity)
+
+            c.SwaggerDoc(
+                            settings.Name,
+                            new OpenApiInfo
+                            {
+                                Version = settings.Version,
+                                Title = settings.Title,
+                                Description = settings.Description,
+                                TermsOfService = new Uri(settings.TermsOfService ?? "https://www.genocs.com/terms_and_conditions.html"),
+                                Contact = new OpenApiContact
+                                {
+                                    Name = settings.ContactName,
+                                    Email = settings.ContactEmail,
+                                    Url = new Uri(settings.ContactUrl ?? "https://www.genocs.com")
+                                },
+                                License = new OpenApiLicense
+                                {
+                                    Name = settings.LicenseName,
+                                    Url = new Uri(settings.LicenseUrl ?? "https://opensource.org/license/mit/")
+                                }
+                            });
+
+            if (settings.IncludeSecurity)
             {
                 c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
                 {
                     Description = "JWT Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\"",
                     Name = "Authorization",
                     In = ParameterLocation.Header,
-                    Type = SecuritySchemeType.ApiKey
+                    Type = SecuritySchemeType.ApiKey,
+                    Scheme = "Bearer"
                 });
+
+                c.AddSecurityRequirement(new OpenApiSecurityRequirement()
+                {
+                    {
+                        new OpenApiSecurityScheme
+                        {
+                            Name = "Bearer",
+                            Reference = new OpenApiReference
+                            {
+                                Type = ReferenceType.SecurityScheme,
+                                Id = "Bearer"
+                            },
+                            Scheme = "oauth2",
+                            In = ParameterLocation.Header
+                        },
+                        new List<string>()
+                    }
+                });
+            }
+
+            // This is required to make the custom operation ids work
+            // It's required to be used by LangChain tools
+            c.CustomOperationIds(oid =>
+            {
+                if (oid.ActionDescriptor is not ControllerActionDescriptor actionDescriptor)
+                {
+                    return null; // default behavior
+                }
+
+                return oid.GroupName switch
+                {
+                    "v1" => $"{actionDescriptor.ActionName}",
+                    _ => $"_{actionDescriptor.ActionName}", // default behavior
+                };
+            });
+
+            // Add list of servers
+
+            if (settings.Servers != null)
+            {
+                foreach (var server in settings.Servers)
+                {
+                    c.AddServer(new OpenApiServer() { Url = server.Url, Description = server.Description });
+                }
             }
+
+            // c.AddServer(new OpenApiServer() { Url = "http://localhost:5300", Description = "Local version to be used for development" });
+            // c.AddServer(new OpenApiServer() { Url = "http://fiscanner-api", Description = "Containerized version to be used into with docker or k8s" });
+            // c.AddServer(new OpenApiServer() { Url = "https://fiscanner-api.azurewebsites.net", Description = "Production deployed on Azure" });
+
+            string documentationFile = Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetEntryAssembly()?.GetName().Name}.xml");
+            c.IncludeXmlComments(documentationFile);
         });
 
         return builder;

src/apps/orders/Genocs.Orders.WebApi/appsettings.json

@@ -133,10 +133,32 @@
   "swagger": {
     "enabled": true,
     "reDocEnabled": false,
-    "name": "v1",
+    "name": "Orders",
     "title": "Orders Service",
-    "version": "v1",
-    "routePrefix": "swagger"
+    "version": "v002",
+    "description": "Orders Service",
+    "routePrefix": "swagger",
+    "termsOfService": "https://www.genocs.com/terms_and_conditions.html",
+    "contactName": "Giovanni Nocco",
+    "contactEmail": "[email protected]",
+    "contactUrl": "https://www.genocs.com",
+    "licenseName": "MIT",
+    "licenseUrl": "https://www.genocs.com/license.html",
+    "includeSecurity": true,
+    "servers": [
+      {
+        "url": "http://localhost:5300",
+        "description": "Local version to be used for development"
+      },
+      {
+        "url": "http://fiscanner-api",
+        "description": "Containerized version to be used into with docker or k8s"
+      },
+      {
+        "url": "https://fiscanner-api.azurewebsites.net",
+        "description": "Production deployed on Azure"
+      }
+    ]
   },
   "redis": {
     "connectionString": "localhost",