Added api documentation/definition system system

Moonlight/Assets/Core/css/scalar.css

@@ -0,0 +1,66 @@
+.light-mode {
+    --scalar-background-1: #fff;
+    --scalar-background-2: #f8fafc;
+    --scalar-background-3: #e7e7e7;
+    --scalar-background-accent: #8ab4f81f;
+    --scalar-color-1: #000;
+    --scalar-color-2: #6b7280;
+    --scalar-color-3: #9ca3af;
+    --scalar-color-accent: #00c16a;
+    --scalar-border-color: #e5e7eb;
+    --scalar-color-green: #069061;
+    --scalar-color-red: #ef4444;
+    --scalar-color-yellow: #f59e0b;
+    --scalar-color-blue: #1d4ed8;
+    --scalar-color-orange: #fb892c;
+    --scalar-color-purple: #6d28d9;
+    --scalar-button-1: #000;
+    --scalar-button-1-hover: rgba(0, 0, 0, 0.9);
+    --scalar-button-1-color: #fff;
+}
+.dark-mode {
+    --scalar-background-1: #020420;
+    --scalar-background-2: #121a31;
+    --scalar-background-3: #1e293b;
+    --scalar-background-accent: #8ab4f81f;
+    --scalar-color-1: #fff;
+    --scalar-color-2: #cbd5e1;
+    --scalar-color-3: #94a3b8;
+    --scalar-color-accent: #00dc82;
+    --scalar-border-color: #1e293b;
+    --scalar-color-green: #069061;
+    --scalar-color-red: #f87171;
+    --scalar-color-yellow: #fde68a;
+    --scalar-color-blue: #60a5fa;
+    --scalar-color-orange: #fb892c;
+    --scalar-color-purple: #ddd6fe;
+    --scalar-button-1: hsla(0, 0%, 100%, 0.9);
+    --scalar-button-1-hover: hsla(0, 0%, 100%, 0.8);
+    --scalar-button-1-color: #000;
+}
+.dark-mode .t-doc__sidebar,
+.light-mode .t-doc__sidebar {
+    --scalar-sidebar-background-1: var(--scalar-background-1);
+    --scalar-sidebar-color-1: var(--scalar-color-1);
+    --scalar-sidebar-color-2: var(--scalar-color-3);
+    --scalar-sidebar-border-color: var(--scalar-border-color);
+    --scalar-sidebar-item-hover-background: transparent;
+    --scalar-sidebar-item-hover-color: var(--scalar-color-1);
+    --scalar-sidebar-item-active-background: transparent;
+    --scalar-sidebar-color-active: var(--scalar-color-accent);
+    --scalar-sidebar-search-background: transparent;
+    --scalar-sidebar-search-color: var(--scalar-color-3);
+    --scalar-sidebar-search-border-color: var(--scalar-border-color);
+    --scalar-sidebar-indent-border: var(--scalar-border-color);
+    --scalar-sidebar-indent-border-hover: var(--scalar-color-1);
+    --scalar-sidebar-indent-border-active: var(--scalar-color-accent);
+}
+.scalar-card .request-card-footer {
+    --scalar-background-3: var(--scalar-background-2);
+    --scalar-button-1: #0f172a;
+    --scalar-button-1-hover: rgba(30, 41, 59, 0.5);
+    --scalar-button-1-color: #fff;
+}
+.scalar-card .show-api-client-button {
+    border: 1px solid #334155 !important;
+}

Moonlight/Core/Attributes/ApiDocumentAttribute.cs

@@ -0,0 +1,11 @@
+namespace Moonlight.Core.Attributes;
+
+public class ApiDocumentAttribute : Attribute
+{
+    public string Name { get; set; }
+    
+    public ApiDocumentAttribute(string name)
+    {
+        Name = name;
+    }
+}

Moonlight/Core/Configuration/CoreConfiguration.cs

@@ -17,6 +17,14 @@ public class CoreConfiguration
     [JsonProperty("Customisation")] public CustomisationData Customisation { get; set; } = new();
 
     [JsonProperty("Security")] public SecurityData Security { get; set; } = new();
+    [JsonProperty("Development")] public DevelopmentData Development { get; set; } = new();
+    
+    public class DevelopmentData
+    {
+        [JsonProperty("EnableApiReference")]
+        [Description("This enables the api reference at your-moonlight.domain/admin/api/reference. Changing this requires a restart")]
+        public bool EnableApiReference { get; set; } = false;
+    }
 
     public class HttpData
     {

Moonlight/Core/CoreFeature.cs

@@ -20,7 +20,10 @@ using Moonlight.Core.Models.Abstractions.Feature;
 using Moonlight.Core.Models.Enums;
 using Moonlight.Core.Repositories;
 using Moonlight.Core.Services;
-using Moonlight.Core.UI.Components.Cards;
+using Microsoft.OpenApi.Models;
+using Moonlight.Core.Attributes;
+using Moonlight.Core.Implementations.ApiDefinition;
+using Swashbuckle.AspNetCore.SwaggerGen;
 
 namespace Moonlight.Core;
 
@@ -108,6 +111,36 @@ public class CoreFeature : MoonlightFeature
         context.AddAsset("Core", "css/sweetalert2dark.css");
         context.AddAsset("Core", "css/utils.css");
 
+        // Api
+        if (config.Development.EnableApiReference)
+        {
+            builder.Services.AddSwaggerGen(async options =>
+            {
+                foreach (var definition in await context.Plugins.GetImplementations<IApiDefinition>())
+                {
+                    options.SwaggerDoc(
+                        definition.GetId(),
+                        new OpenApiInfo()
+                        {
+                            Title = definition.GetName(),
+                            Version = definition.GetVersion()
+                        }
+                    );
+                }
+
+                options.SwaggerGeneratorOptions.DocInclusionPredicate = (document, description) =>
+                {
+                    foreach (var attribute in description.CustomAttributes())
+                    {
+                        if (attribute is ApiDocumentAttribute documentAttribute)
+                            return document == documentAttribute.Name;
+                    }
+
+                    return false;
+                };
+            });
+        }
+
         return Task.CompletedTask;
     }
 
@@ -115,6 +148,10 @@ public class CoreFeature : MoonlightFeature
     {
         var app = context.Application;
 
+        // Config
+        var configService = app.Services.GetRequiredService<ConfigService<CoreConfiguration>>();
+        var config = configService.Get();
+
         // Allow MoonlightService to access the app
         var moonlightService = app.Services.GetRequiredService<MoonlightService>();
         moonlightService.Application = app;
@@ -140,6 +177,12 @@ public class CoreFeature : MoonlightFeature
             Description = "Allows to see the raw message of exceptions when thrown in a view"
         });
 
+        await permissionService.Register(9998, new()
+        {
+            Name = "Manage admin api access",
+            Description = "Allows access to manage api keys and their permissions"
+        });
+        
         await permissionService.Register(9999, new()
         {
             Name = "Manage system",
@@ -205,6 +248,14 @@ public class CoreFeature : MoonlightFeature
 
             Logger.Info($"Default login: Email: '{email}' Password: '{password}'");
         });
+
+        // Api
+        if (config.Development.EnableApiReference)
+        {
+            app.MapSwagger("/api/core/reference/openapi/{documentName}");
+
+            await pluginService.RegisterImplementation<IApiDefinition>(new InternalApiDefinition());
+        }
     }
 
     public override Task OnUiInitialized(UiInitContext context)
@@ -215,7 +266,8 @@ public class CoreFeature : MoonlightFeature
         context.AddSidebarItem("Dashboard", "bxs-dashboard", "/", needsExactMatch: true, index: int.MinValue);
 
         // Admin pages
-        context.AddSidebarItem("Dashboard", "bxs-dashboard", "/admin", needsExactMatch: true, isAdmin: true, index: int.MinValue);
+        context.AddSidebarItem("Dashboard", "bxs-dashboard", "/admin", needsExactMatch: true, isAdmin: true,
+            index: int.MinValue);
         context.AddSidebarItem("Users", "bxs-group", "/admin/users", needsExactMatch: false, isAdmin: true);
         context.AddSidebarItem("System", "bxs-component", "/admin/sys", needsExactMatch: false, isAdmin: true);
 
@@ -253,10 +305,7 @@ public class CoreFeature : MoonlightFeature
         };
 
         // Setup updating
-        navigationManager.LocationChanged += (_, _) =>
-        {
-            session.UpdatedAt = DateTime.UtcNow;
-        };
+        navigationManager.LocationChanged += (_, _) => { session.UpdatedAt = DateTime.UtcNow; };
 
         // Save session and session service to view storage
         scopedStorageService.Set("Session", session);

Moonlight/Core/Http/Controllers/ApiReferenceController.cs

@@ -0,0 +1,53 @@
+using Microsoft.AspNetCore.Mvc;
+using MoonCore.Services;
+using Moonlight.Core.Attributes;
+using Moonlight.Core.Configuration;
+using Moonlight.Core.Models;
+using Newtonsoft.Json;
+
+namespace Moonlight.Core.Http.Controllers;
+
+[ApiController]
+[ApiDocument("internal")]
+[Route("/api/core/reference")]
+public class ApiReferenceController : Controller
+{
+    private readonly ConfigService<CoreConfiguration> ConfigService;
+
+    public ApiReferenceController(ConfigService<CoreConfiguration> configService)
+    {
+        ConfigService = configService;
+    }
+
+    [HttpGet]
+    public async Task<ActionResult> Get([FromQuery] string document)
+    {
+        if (!ConfigService.Get().Development.EnableApiReference)
+            return BadRequest("Api reference is disabled");
+        
+        var options = new ScalarOptions();
+        var optionsJson = JsonConvert.SerializeObject(options, Formatting.Indented);
+
+        var html = "<!doctype html>\n" +
+                   "<html>\n" +
+                   "<head>\n" +
+                   "<title>Moonlight Api Reference</title>\n" +
+                   "<meta charset=\"utf-8\" />\n" +
+                   "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n" +
+                   "</head>\n" +
+                   "<body>\n" +
+                   $"<script id=\"api-reference\" data-url=\"/api/core/reference/openapi/{document}\"></script>\n" +
+                   "<script>\n" +
+                   "var configuration =\n" +
+                   $"{optionsJson}\n" +
+                   "\n" +
+                   "document.getElementById('api-reference').dataset.configuration =\n" +
+                   "JSON.stringify(configuration)\n" +
+                   "</script>\n" +
+                   "<script src=\"https://cdn.jsdelivr.net/npm/@scalar/api-reference\"></script>\n" +
+                   "</body>\n" +
+                   "</html>";
+
+        return Content(html, "text/html");
+    }
+}

Moonlight/Core/Http/Controllers/AssetController.cs

@@ -1,9 +1,11 @@
 using Microsoft.AspNetCore.Mvc;
 using MoonCore.Helpers;
+using Moonlight.Core.Attributes;
 
 namespace Moonlight.Core.Http.Controllers;
 
 [ApiController]
+[ApiDocument("internal")]
 [Route("api/core/asset")]
 public class AssetController : Controller
 {

Moonlight/Core/Http/Controllers/AvatarController.cs

@@ -4,6 +4,7 @@ using Microsoft.AspNetCore.Mvc;
 using MoonCore.Abstractions;
 using MoonCore.Helpers;
 using MoonCore.Services;
+using Moonlight.Core.Attributes;
 using Moonlight.Core.Configuration;
 using Moonlight.Core.Database.Entities;
 using Moonlight.Core.Services;
@@ -11,6 +12,7 @@ using Moonlight.Core.Services;
 namespace Moonlight.Core.Http.Controllers;
 
 [ApiController]
+[ApiDocument("internal")]
 [Route("api/core/avatar")]
 public class AvatarController : Controller
 {

Moonlight/Core/Implementations/ApiDefinition/InternalApiDefinition.cs

@@ -0,0 +1,14 @@
+using Moonlight.Core.Interfaces;
+
+namespace Moonlight.Core.Implementations.ApiDefinition;
+
+public class InternalApiDefinition : IApiDefinition
+{
+    public string GetId() => "internal";
+
+    public string GetName() => "Internal API";
+
+    public string GetVersion() => "v2";
+
+    public string[] GetPermissions() => [];
+}

Moonlight/Core/Interfaces/IApiDefinition.cs

@@ -0,0 +1,9 @@
+namespace Moonlight.Core.Interfaces;
+
+public interface IApiDefinition
+{
+    public string GetId();
+    public string GetName();
+    public string GetVersion();
+    public string[] GetPermissions();
+}

Moonlight/Core/Models/Abstractions/Feature/PreInitContext.cs

@@ -1,4 +1,5 @@
 using System.Reflection;
+using Moonlight.Core.Services;
 
 namespace Moonlight.Core.Models.Abstractions.Feature;
 
@@ -7,6 +8,7 @@ public class PreInitContext
     public WebApplicationBuilder Builder { get; set; }
     public List<Assembly> DiAssemblies { get; set; } = new();
     public Dictionary<string, List<string>> Assets { get; set; } = new();
+    public PluginService Plugins { get; set; }
     
     public void EnableDependencyInjection<T>()
     {

Moonlight/Core/Models/ScalarOptions.cs

@@ -0,0 +1,43 @@
+namespace Moonlight.Core.Models;
+
+// From https://github.com/scalar/scalar/blob/main/packages/scalar.aspnetcore/ScalarOptions.cs
+
+public class ScalarOptions
+{
+    public string Theme { get; set; } = "purple";
+
+    public bool? DarkMode { get; set; }
+    public bool? HideDownloadButton { get; set; }
+    public bool? ShowSideBar { get; set; }
+
+    public bool? WithDefaultFonts { get; set; }
+
+    public string? Layout { get; set; }
+
+    public string? CustomCss { get; set; }
+
+    public string? SearchHotkey { get; set; }
+
+    public Dictionary<string, string>? Metadata { get; set; }
+
+    public ScalarAuthenticationOptions? Authentication { get; set; }
+}
+
+public class ScalarAuthenticationOptions
+{
+    public string? PreferredSecurityScheme { get; set; }
+
+    public ScalarAuthenticationApiKey? ApiKey { get; set; }
+}
+
+public class ScalarAuthenticationoAuth2
+{
+    public string? ClientId { get; set; }
+
+    public List<string>? Scopes { get; set; }
+}
+
+public class ScalarAuthenticationApiKey
+{
+    public string? Token { get; set; }
+}

Moonlight/Core/Services/FeatureService.cs

@@ -55,11 +55,12 @@ public class FeatureService
         return Task.CompletedTask;
     }
 
-    public async Task PreInit(WebApplicationBuilder builder)
+    public async Task PreInit(WebApplicationBuilder builder, PluginService pluginService)
     {
         Logger.Info("Pre-initializing features");
 
         PreInitContext.Builder = builder;
+        PreInitContext.Plugins = pluginService;
 
         foreach (var feature in Features)
         {

Moonlight/Program.cs

@@ -105,7 +105,7 @@ builder.Services.AddSingleton(configService);
 builder.Services.AddSingleton(pluginService);
 
 // Feature hook
-await featureService.PreInit(builder);
+await featureService.PreInit(builder, pluginService);
 
 // Plugin hook
 await pluginService.PreInitialize(builder);