Fix descriptions, add module ID to OpenAPI (#2944)

Co-authored-by: Artem Dudarev <[email protected]>

Author: asvishnyakov

src/VirtoCommerce.Platform.Web/Swagger/ModuleInfoFilter.cs

@@ -0,0 +1,100 @@
+using System.Collections.Generic;
+using System.Linq;
+using Microsoft.AspNetCore.Mvc.Controllers;
+using Microsoft.OpenApi.Any;
+using Microsoft.OpenApi.Interfaces;
+using Microsoft.OpenApi.Models;
+using Swashbuckle.AspNetCore.SwaggerGen;
+using VirtoCommerce.Platform.Core.Common;
+using VirtoCommerce.Platform.Core.Modularity;
+
+namespace VirtoCommerce.Platform.Web.Swagger;
+
+/// <summary>
+/// This operation filter assigns module info (such as name and id) to operations based on their module association.
+/// </summary>
+public class ModuleInfoFilter : IOperationFilter, IDocumentFilter
+{
+    private const string _moduleIdExtension = "x-virtocommerce-module-id";
+
+    private readonly Dictionary<string, SwaggerModule> _moduleByTitle;
+    private readonly Dictionary<string, SwaggerModule> _moduleByAssemblyName;
+
+    /// <summary>
+    /// This operation filter assigns module info (such as name and id) to operations based on their module association.
+    /// </summary>
+    public ModuleInfoFilter(IModuleCatalog moduleCatalog)
+    {
+        var modules = moduleCatalog.Modules
+            .OfType<ManifestModuleInfo>()
+            .Where(x => x.ModuleInstance != null)
+            .Select(x =>
+                new SwaggerModule
+                {
+                    Id = x.Id,
+                    Title = x.Title,
+                    Description = x.Description,
+                    AssemblyName = x.ModuleInstance.GetType().Assembly.GetName().Name,
+                })
+            .ToList();
+
+        modules.Insert(0, new SwaggerModule
+        {
+            Id = "VirtoCommerce.Platform",
+            Title = "VirtoCommerce Platform",
+            AssemblyName = GetType().Assembly.GetName().Name,
+        });
+
+        _moduleByTitle = modules.ToDictionary(x => x.Title);
+        _moduleByAssemblyName = modules.ToDictionary(x => x.AssemblyName);
+    }
+
+    public void Apply(OpenApiOperation operation, OperationFilterContext context)
+    {
+        var controllerAssemblyName = ((ControllerActionDescriptor)context.ApiDescription.ActionDescriptor).ControllerTypeInfo.Assembly.GetName().Name;
+
+        if (_moduleByAssemblyName.TryGetValueSafe(controllerAssemblyName, out var module))
+        {
+            operation.Tags = [new OpenApiTag { Name = module.Title }];
+            operation.Extensions[_moduleIdExtension] = new OpenApiString(module.Id);
+        }
+    }
+
+    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
+    {
+        swaggerDoc.Tags ??= [];
+
+        // Collect unique tag names from operations
+        var operationTagNames = swaggerDoc.Paths
+            .SelectMany(path => path.Value.Operations.Values)
+            .SelectMany(operation => operation.Tags ?? [])
+            .Select(tag => tag.Name)
+            .Distinct()
+            .ToList();
+
+        // Add tags at document level with descriptions and extensions
+        foreach (var tagName in operationTagNames)
+        {
+            if (_moduleByTitle.TryGetValue(tagName, out var module))
+            {
+                swaggerDoc.Tags.Add(new OpenApiTag
+                {
+                    Name = module.Title,
+                    Description = module.Description,
+                    Extensions = new Dictionary<string, IOpenApiExtension>
+                    {
+                        { _moduleIdExtension, new OpenApiString(module.Id) },
+                    },
+                });
+            }
+        }
+    }
+
+    private sealed class SwaggerModule
+    {
+        public string Id { get; init; }
+        public string Title { get; init; }
+        public string Description { get; init; }
+        public string AssemblyName { get; init; }
+    }
+}

src/VirtoCommerce.Platform.Web/Swagger/SwaggerServiceCollectionExtensions.cs

@@ -78,14 +78,15 @@ public static void AddSwagger(this IServiceCollection services, IConfiguration c
                 c.TagActionsBy(api => [api.GetModuleName(provider)]);
                 c.IgnoreObsoleteActions();
                 c.DocumentFilter<ExcludeRedundantDepsFilter>();
+                c.DocumentFilter<ModuleInfoFilter>();
                 // This temporary filter removes broken "application/*+json" content-type.
                 // It seems it's some openapi/swagger bug, because Autorest fails.
                 c.OperationFilter<ConsumeFromBodyFilter>();
                 c.OperationFilter<FileResponseTypeFilter>();
                 c.OperationFilter<OptionalParametersFilter>();
                 c.OperationFilter<ArrayInQueryParametersFilter>();
                 c.OperationFilter<SecurityRequirementsOperationFilter>();
-                c.OperationFilter<TagsFilter>();
+                c.OperationFilter<ModuleInfoFilter>();
                 c.OperationFilter<OpenIDEndpointDescriptionFilter>();
                 c.SchemaFilter<EnumSchemaFilter>();
                 c.SchemaFilter<SwaggerIgnoreFilter>();
@@ -141,7 +142,7 @@ private static bool DocInclusionPredicateCustomStrategy(ManifestModuleInfo[] mod
                 return true;
             }
 
-            // It's a module endpoint. 
+            // It's a module endpoint.
             var module = modules.FirstOrDefault(m => m.ModuleName.EqualsIgnoreCase(docName));
             return module != null && module.Assembly == currentAssembly;
         }
@@ -172,7 +173,7 @@ public static void UseSwagger(this IApplicationBuilder applicationBuilder)
             // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), specifying the Swagger JSON endpoint.
             applicationBuilder.UseSwaggerUI(c =>
             {
-                // Json Format Support 
+                // Json Format Support
                 c.SwaggerEndpoint($"./{PlatformUIDocName}/swagger.json", PlatformUIDocName);
                 c.SwaggerEndpoint($"./{PlatformDocName}/swagger.json", PlatformDocName);
 
@@ -242,7 +243,7 @@ private static void AddModulesXmlComments(this SwaggerGenOptions options, Servic
 
             foreach (var path in xmlCommentsDirectoryPaths)
             {
-                var xmlComments = Directory.GetFiles(path, "*.XML");
+                var xmlComments = Directory.GetFiles(path, "*.xml", new EnumerationOptions { MatchCasing = MatchCasing.CaseInsensitive });
                 foreach (var xmlComment in xmlComments)
                 {
                     options.IncludeXmlComments(xmlComment);

src/VirtoCommerce.Platform.Web/Swagger/TagsFilter.cs

@@ -93,7 +93,7 @@ body
 
 .swagger-section .swagger-ui-wrap ul#resources,
 .swagger-ui .opblock-tag,
-.swagger-ui .opblock-tag small
+.swagger-ui .opblock-tag small,
 .swagger-ui .opblock .opblock-summary-operation-id,
 .swagger-ui .opblock .opblock-summary-path,
 .swagger-ui .opblock .opblock-summary-path__deprecated,
@@ -126,30 +126,46 @@ body
 
 .swagger-ui .opblock-tag
 {
-    /* display: block; */
-    clear: none;
-    float: left;
+    display: block !important;
+    position: relative;
     font-weight: bold;
     font-size: 1.3em;
-    padding: 10px 0 10px 0;
+    padding: 10px 40px 10px 0;
+}
+
+.swagger-ui .opblock-tag small
+{
+    margin-top: 5px;
+    padding: 0;
+}
+
+.swagger-ui .opblock-tag small .renderedMarkdown p {
+    margin: 5px 0;
+}
+
+.swagger-ui .opblock-tag .expand-operation {
+    position: absolute;
+    top: 0;
+    right: 0;
+    height: 100%
 }
 
 .swagger-ui .opblock
 {
     border-radius: 0px;
 }
 
-.swagger-ui .opblock .opblock-summary-operation-id, 
-.swagger-ui .opblock .opblock-summary-path, 
+.swagger-ui .opblock .opblock-summary-operation-id,
+.swagger-ui .opblock .opblock-summary-path,
 .swagger-ui .opblock .opblock-summary-path__deprecated,
-.swagger-ui .opblock .opblock-summary-method 
+.swagger-ui .opblock .opblock-summary-method
 {
     font-family: 'Exo 2';
     font-weight: bold;
     font-size: 0.9em;
 }
 
-.swagger-ui .opblock .opblock-summary-method 
+.swagger-ui .opblock .opblock-summary-method
 {
     padding: 5px;
     border-radius:0;