openapi support added

Author: HaikAsatryan

Readme.md

@@ -1,13 +1,117 @@
-# Pandatech.***
+# Pandatech.SharedKernel
 
-## Introduction
+Welcome to the `Pandatech.SharedKernel` NuGet package, a centralized library designed to streamline development across all PandaTech projects. This package consolidates shared configurations, utilities, and extensions into a single, reusable resource.
 
-## Features
+Though this package is primarily intended for internal use, it is publicly available for anyone who may find it useful. We recommend forking or copying the classes in this repository and creating your own package to suit your needs.
 
-## Installation
+By leveraging this shared kernel, we aim to:
 
-## Usage
+- Reduce the amount of boilerplate code required to start a new project.
+- Ensure consistency across all PandaTech projects.
+- Simplify the process of updating shared configurations and utilities.
 
-## License
+## Scope
 
-Pandatech.*** is licensed under the MIT License.
+This package currently supports:
+
+- **OpenAPI Configuration** with SwaggerUI and Scalar.
+
+
+## OpenAPI
+
+`Microsoft.AspNetCore.OpenApi` is the new standard for creating OpenAPI JSON files. We have adopted this library instead of Swashbuckle for generating OpenAPI definitions. While using this new library, we have integrated `SwaggerUI` and `Scalar` to provide user-friendly interfaces in addition to the JSON files.
+
+### Key Features
+
+- **Multiple API Documents:** Easily define and organize multiple API documentation groups.
+- **Enum String Values:** Enum string values are automatically displayed in the documentation, simplifying integration for external partners.
+- **Customizable SwaggerUI:** Add custom styles and JavaScript to tailor the UI.
+- **Security Schemes:** Configure security headers directly in your OpenAPI settings.
+
+
+### Adding OpenAPI to Your Project
+
+To enable OpenAPI in your project, add the following code:
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+builder.AddOpenApi();
+var app = builder.Build();
+app.UseOpenApi();
+app.Run();
+```
+
+You can also customize the `AddOpenApi` method with options:
+
+```csharp
+builder.AddOpenApi(options =>
+{
+    options.AddSchemaTransformer<CustomSchemaTransformer>();
+});
+```
+
+### Configuration
+
+Add the following configuration to your `appsettings.json` file:
+
+```json
+{
+    "OpenApi": {
+        "DisabledEnvironments": [
+            "Production"
+        ],
+        "SecuritySchemes": [
+            {
+                "HeaderName": "Authorization",
+                "Description": "Access token for the API."
+            }
+        ],
+        "Documents": [
+            {
+                "Title": "Admin Panel API",
+                "Description": "API for administrative functions.",
+                "GroupName": "admin-v1",
+                "Version": "v1",
+                "ForExternalUse": false
+            },
+            {
+                "Title": "Integration",
+                "Description": "Integration API Endpoints",
+                "GroupName": "integration-v1",
+                "Version": "v1",
+                "ForExternalUse": true
+            }
+        ],
+        "Contact": {
+            "Name": "Pandatech",
+            "Url": "https://pandatech.it",
+            "Email": "[email protected]"
+        }
+    },
+    "SwaggerUi": {
+        "InjectedCssPaths": [
+            "/assets/css/panda-style.css"
+        ],
+        "InjectedJsPaths": [
+            "/assets/js/docs.js"
+        ]
+    },
+    "ScalarUi": {
+        "FaviconPath": "/assets/images/favicon.svg"
+    }
+}
+```
+
+### Notes
+
+- **For External Use:** If you set `ForExternalUse: true` for a document, it will be available both within the regular SwaggerUI and a separate SwaggerUI instance. This allows you to provide a dedicated URL to external partners while keeping internal documents private.
+- **Scalar UI Limitations:** Scalar currently does not support multiple documents within a single URL. Consequently, all documents in Scalar will be separated into individual URLs. Support for multiple documents is expected in future Scalar updates.
+
+### Example URLs
+
+Based on the above configuration, the UI will be accessible at the following URLs:
+
+- **Swagger (all documents):** [http://localhost/swagger](http://localhost/swagger)
+- **Swagger (external document only):** [http://localhost/doc/integration-v1](http://localhost/doc/integration-v1)
+- **Scalar (admin document):** [http://localhost/scalar/admin-v1](http://localhost/scalar/admin-v1)
+- **Scalar (integration document):** [http://localhost/scalar/integration-v1](http://localhost/scalar/integration-v1)

PandaNuGet.sln SharedKernel.slnPandaNuGet.sln renamed to SharedKernel.sln

@@ -1,6 +1,6 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PandaNuGet", "src\PandaNuGet\PandaNuGet.csproj", "{25001943-A870-4E17-A9B9-0D190CEC819B}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SharedKernel", "src\SharedKernel\SharedKernel.csproj", "{25001943-A870-4E17-A9B9-0D190CEC819B}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PandaNuGet.Tests", "test\PandaNuGet.Tests\PandaNuGet.Tests.csproj", "{0305E58F-1C47-454C-B10B-A223F2561A85}"
 EndProject

src/PandaNuGet/PandaNuGet.csproj

@@ -1,4 +1,4 @@
-namespace PandaNuGet;
+namespace SharedKernel;
 
 public class Class1
 {

src/PandaNuGet/Class1.cs src/SharedKernel/Class1.cssrc/PandaNuGet/Class1.cs renamed to src/SharedKernel/Class1.cs

@@ -0,0 +1,28 @@
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.OpenApi.Models;
+
+namespace SharedKernel.OpenApi;
+
+internal class EnumSchemaTransformer : IOpenApiSchemaTransformer
+{
+   public Task TransformAsync(OpenApiSchema schema,
+      OpenApiSchemaTransformerContext context,
+      CancellationToken cancellationToken)
+   {
+      var type = context.JsonTypeInfo.Type;
+
+      if (!type.IsEnum)
+      {
+         return Task.CompletedTask;
+      }
+
+      var enumDescriptions = Enum.GetValues(type)
+                                 .Cast<object>()
+                                 .Select(value => $"{value} = {(int)value}")
+                                 .ToList();
+
+      schema.Description = string.Join(", ", enumDescriptions);
+
+      return Task.CompletedTask;
+   }
+}

src/SharedKernel/OpenApi/EnumSchemaTransformer.cs

@@ -0,0 +1,140 @@
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using RegexBox;
+using Scalar.AspNetCore;
+using SharedKernel.OpenApi.Options;
+
+namespace SharedKernel.OpenApi;
+
+public static class OpenApiExtensions
+{
+   public static WebApplicationBuilder AddOpenApi(this WebApplicationBuilder builder, Action<OpenApiOptions>? configureOptions = null)
+   {
+      var openApiConfiguration = builder.Configuration
+                                        .GetSection("OpenApi")
+                                        .Get<OpenApiConfig>();
+
+      if (builder.Environment.IsOpenApiConfigValidAndDisabled(openApiConfiguration))
+      {
+         return builder;
+      }
+      
+
+      foreach (var document in openApiConfiguration.Documents)
+      {
+         builder.Services.AddOpenApi(document.GroupName,
+            options =>
+            {
+               options.AddDocument(document, openApiConfiguration);
+               options.AddSchemaTransformer<EnumSchemaTransformer>();
+               options.UseApiSecuritySchemes(openApiConfiguration);
+               configureOptions?.Invoke(options);
+            });
+      }
+
+      return builder;
+   }
+
+   public static WebApplication UseOpenApi(this WebApplication app)
+   {
+      var openApiConfiguration = app.Configuration
+                                    .GetSection("OpenApi")
+                                    .Get<OpenApiConfig>();
+
+      if (app.Environment.IsOpenApiConfigValidAndDisabled(openApiConfiguration))
+      {
+         return app;
+      }
+
+      app.MapStaticAssets();
+      app.MapOpenApi();
+      app.MapSwaggerUi(openApiConfiguration);
+      app.MapScalarApiReference(options =>
+      {
+         options.Theme = ScalarTheme.Kepler;
+         options.Favicon = "/assets/images/favicon.svg";
+      });
+      return app;
+   }
+
+   private static bool IsOpenApiConfigValidAndDisabled(this IHostEnvironment environment,
+      [NotNull] OpenApiConfig? openApiConfiguration)
+   {
+      if (openApiConfiguration is null || openApiConfiguration.Documents.Count == 0)
+      {
+         throw new InvalidOperationException("OpenApi configuration is missing or contains no documents.");
+      }
+
+      // Validate Contact
+      if (openApiConfiguration.Contact is null)
+      {
+         throw new InvalidOperationException("Contact configuration is required in OpenApi.");
+      }
+
+      if (string.IsNullOrWhiteSpace(openApiConfiguration.Contact.Name))
+      {
+         throw new InvalidOperationException("Contact Name is required in OpenApi configuration.");
+      }
+
+      if (!PandaValidator.IsUri(openApiConfiguration.Contact.Url))
+      {
+         throw new InvalidOperationException("Contact URL must be a valid URL in OpenApi configuration.");
+      }
+
+      if (!PandaValidator.IsEmail(openApiConfiguration.Contact.Email))
+      {
+         throw new InvalidOperationException("Contact Email is required in OpenApi configuration.");
+      }
+
+      // Validate OpenApi documents
+      foreach (var document in openApiConfiguration.Documents)
+      {
+         if (string.IsNullOrWhiteSpace(document.Title))
+         {
+            throw new InvalidOperationException("Document Title is required in OpenApi configuration.");
+         }
+
+         if (string.IsNullOrWhiteSpace(document.Description))
+         {
+            throw new InvalidOperationException(
+               $"Document Description is required for document '{document.Title}' in OpenApi configuration.");
+         }
+
+         if (string.IsNullOrWhiteSpace(document.GroupName))
+         {
+            throw new InvalidOperationException(
+               $"GroupName is required for document '{document.Title}' in OpenApi configuration.");
+         }
+
+         if (string.IsNullOrWhiteSpace(document.Version))
+         {
+            throw new InvalidOperationException(
+               $"Version is required for document '{document.Title}' in OpenApi configuration.");
+         }
+
+         document.GroupName = document.GroupName.ToLowerInvariant();
+      }
+
+      // Validate SecuritySchemes
+      foreach (var schema in openApiConfiguration.SecuritySchemes)
+      {
+         if (string.IsNullOrWhiteSpace(schema.HeaderName))
+         {
+            throw new InvalidOperationException("SecuritySchema HeaderName is required in OpenApi configuration..");
+         }
+
+         if (string.IsNullOrWhiteSpace(schema.Description))
+         {
+            throw new InvalidOperationException(
+               $"Description is required for SecuritySchema with HeaderName '{schema.HeaderName}' in OpenApi configuration..");
+         }
+      }
+
+      // Check if the environment is disabled
+      return openApiConfiguration.DisabledEnvironments.Contains(environment.EnvironmentName);
+   }
+}